Filter results by

Develop an application

In this article, we explain how you can develop an application that utilizes a device built by another ARTIK cloud services developer. We describe the high-level steps for three phases of app development, as well as best practices for productization.

Our example application gets the state of a fire detector and displays it to the user. In a real-world scenario, the fire detector would have been built for ARTIK cloud services by another developer and owned by the end user of our application.

For an introduction to device development on ARTIK cloud services, read:

How to develop an ARTIK Cloud application

Basic steps for prototyping

Step 1: Browse device types on ARTIK cloud services

Visit our Works With page to review the device types we have verified to work with ARTIK cloud services.

You can find even more device types when creating an application in the Developer Dashboard in Step 2. When you set permissions for your application, you will find a list of device types that have been published on ARTIK cloud services.

How to develop an ARTIK Cloud application

Each device type is shown with its unique device type name, which you will need later.

Check out the Manifest for a device type that interests you. A Manifest provides must-have info for app development: the data fields and Actions that are supported by the device type. Log into the API Console and call Get Latest Manifest Properties to get the Manifest.

You should now be able to decide which device types your application can work with.

Step 2: Create an application and request permissions

Follow our steps to create an ARTIK cloud services application in the Developer Dashboard.

You can start simple by selecting the Implicit OAuth method. This authentication method is the easiest to implement, but less secure.

Request READ permissions on the user profile and device. Our page should look like this:

How to develop an ARTIK Cloud application

Step 3: Obtain an access token and device info

We're done setting up on ARTIK cloud services. Let's start developing!

Implement the login flow and obtain the user token (one of the three types of access tokens). Ensure the implemented OAuth method is consistent with the one you set in Step 2.

Since the application reads the data from the device, the app must have the device ID. For prototyping, you can manually get the device ID at My ARTIK Cloud.

Step 4: Call APIs

You now have the device ID and access token (user token). Now your application can make API calls to get the device data from ARTIK cloud services. The simplest way is to make a GET call using the REST API.

1
2
GET: https://api.artik.cloud/v1.1/messages/last?count=1&sdids=<YOUR DEVICE ID>
Headers: {"Authorization": "bearer <YOUR ACCESS TOKEN>"}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Response: 
{
  "sdids": "absd",
  "count": 1,
  "size": 1,
  "data": [
    {
      "mid": "f0171894044a40a9808f8d8de0baf2cf",
      "data": {
        "onFire": false,
      },
      "ts": 1492016370000,
      "sdtid": "dtce457035",
      "cts": 1492016370764,
      "uid": "240bc34cf61348e6a3255fe5d8539484",
      "mv": 1,
      "sdid": "absd"
    }
  ]
}

Step 5: Test monitoring app

At My ARTIK Cloud, start the Online Device Simulator on the device.

How to develop an ARTIK Cloud application

Configure the simulation parameters. The following is an example.

How to develop an ARTIK Cloud application

You should see the new data on your app while the simulation is running.

Add control and real-time monitoring functionalities

Let's make our prototype app more useful. As shown below, the new version of the app controls (turns on/off) a smart light and receives its latest state in near real-time. We can modify some of the above steps to achieve this.

For full implementation details, read:

How to develop an ARTIK Cloud application

Request WRITE permissions for device type

In Step 2 we requested READ permission for the device type, which is sufficient for a monitoring app.

To send Actions to a device, the app should ask for device type READ and WRITE permissions:

How to develop an ARTIK Cloud application

Real-time monitoring

As mentioned in Step 4, making a REST call is the simplest way to get the latest state from the device.

In practice, we recommend establishing a Firehose WebSocket connection between the app and ARTIK cloud services. This way, the app receives the latest state from the device in near real-time without pulling periodically.

Send Actions

POSTing an Action is the simplest way to send an Action:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST: https://api.artik.cloud/v1.1/actions
Headers: {"Authorization": "bearer <YOUR ACCESS TOKEN>"}, 
Request:
{
    "data": {
        "actions": [
            {
                "name": "setOn",
                "parameters": {}
            }
        ]
    },
    "ddid": "<SMART LIGHT DEVICE ID>",
    "type": "action"
}

Follow Step 3 to obtain the device ID of the smart light.

When the light acts on a received Action, the app's monitoring functionality will show the light's new state.

Test the Actions

  1. Send Actions to the device on the app.
  2. See the Data Logs (Actions tab) at My ARTIK Cloud to see the Actions sent by the app.

To test the monitoring functionality, follow Step 5. You should see the new data received by your app in near real-time.

Add Rules functionality

Let's move to the next phase of app development, in which our application creates and manages Rules for the end user's devices.

In the following example, the app programmatically sets up two Rules in ARTIK cloud services. Then the source device (fire detector) can control the destination device (smart light).

In contrast to the previous example, ARTIK cloud services (not the application) send the Actions to the smart light.

For full implementation details, read:

How to develop an ARTIK Cloud application

Request WRITE permissions for all device types

The app must request READ and WRITE permissions for all device types included in the Rules:

How to develop an ARTIK Cloud application

Create Rules

Follow our steps to construct the Rule body. Then make a POST call to create a Rule. The following is the HTTP request for turning on the light.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST: https://api.artik.cloud/v1.1/actions
Headers: {"Authorization": "bearer <YOUR ACCESS TOKEN>"}, 
Request:
{
    "description": "If onFire is true, turn on the light",
    "enabled": true,
    "name": "rule turning on light ",
    "rule": {
        "if": {
            "and": [
                {
                    "sdid": "<FIRE DETECTOR DEVICE ID>",
                    "field": "onFire",
                    "operator": "=",
                    "operand": {
                        "value": true
                    }
                }
            ]
        },
        "then": [
            {
                "ddid": "<SMART LIGHT DEVICE ID>",
                "action": "setOn"
            }
        ]
    }
}

A similar API call creates the Rule to turn off the light.

Manage Rules

Your application can use the Rules APIs to enable end users to manage their Rules. For example:

Your application can only see and manage Rules it has created.

Test the Rules

Let's verify that the Rules are properly created:

  1. Have your application create the Rules for the user.
  2. Log into My ARTIK Cloud as that user and start the Online Device Simulator for the source device (fire detector). We also did this in Step 5 to test the monitoring app.
  3. To verify that the smart light receives the corresponding Actions, visit the Data Logs (Actions tab) at My ARTIK Cloud. You should see that the correct Actions are received by the smart light:

How to develop an ARTIK Cloud application

From prototyping to production

Choose access tokens

ARTIK cloud services have three types of access tokens: device, user, and application tokens.

By default, all ARTIK cloud services APIs accept all three access tokens unless otherwise specified.

A user token is sufficient in some real-world scenarios. The application presents a mobile or web UI for the user to login, requests permissions, and finally obtains the user token.

If your application needs to get/update data for multiple users, consider also using an application token alongside the user token. As with the user token, permissions must first be granted by the device owner via the application's mobile or web UI. Back-end servers can then generate and use an application token.

Choose OAuth methods

To obtain a user token, the app needs to implement at least one of the three OAuth methods: Implicit, Authorization Code, Authorization Code with PKCE.

We used the Implicit method here for its simplicity. In practice, consider using Authorization Code or Authorization Code with PKCE for improved security. We suggest using an existing library to implement an OAuth2 flow, such as AppAuth for Android, iOS, and OS X.

To obtain an application token, use the Client Credentials method, which has a straightforward implementation.

See Selecting authentication methods to learn about best practices.

Get device info programmatically

In our prototype, we manually get the device ID at My ARTIK Cloud to use in the application code. In practice, an application should do this programmatically. For example:

  1. Connect a device, then get the device ID
  2. Get the list of a user's devices, then find the device ID of a specific device

Check the REST APIs to find other methods that may suit your needs.

Send or receive messages/Actions

These are the available methods of sending and receiving data in ARTIK cloud services.

To send an Action to a device via ARTIK cloud services:

  1. REST: Post an Action
  2. WebSocket: Send via a device channel WebSocket in near real-time

To have an application receive data messages or Actions:

  1. REST: Messages APIs, e.g. Get last normalized messages, Get normalized Actions, etc.
  2. WebSocket: Use a Firehose WebSocket to receive data messages in near real-time
  3. Subscribing with the httpCallback type, then receiving messages and/or Actions in notifications
  4. Amazon Kinesis can be set up to receive messages and/or Actions from ARTIK cloud services (sample system)

Work with Cloud Connector devices

Your application can also work with Cloud Connector devices owned by the user. Cloud Connectors enable third-party clouds to become part of the ARTIK cloud services ecosystem, where they are treated as regular devices. This How To article explains how to add Cloud Connector devices to an application.