EVRYTHNG Developer Hub

Welcome! Here's where you'll find what you need to start working with EVRYTHNG as quickly as possible. There are comprehensive guides, documentation, and support if you get stuck. We encourage you to dive in and explore.

Create Free Account Read Documentation

Connected Products

The EVRYTHNG API not only supports tagged products, but was especially designed to handle a large number of highly connected products and embedded controllers such as Arduino, Raspberry Pi, Spark, OpenPicus, Marvell, Edison, Broadcom and many others.


General Concepts

In this section, we briefly review the various resources available in our platform and how they can be used in the context of connected products.

Thngs, Properties, and Actions

In our platform, any physical device (e.g., a smart thermostat) becomes a Thng. Thngs have a number of properties which store the status of the device (e.g., values of a temperature sensor) as dynamic key-value data in a time series.

Thngs can also support various actions, which are commands that applications can send to the device through our cloud (e.g. turn on/off the thermostat, change the current set temperature). Examples of actions are “open/close the garage door,” “turn on the living room light, set its brightness to 50%, and set the color to red,” and “turn off the TV in 30 minutes.” In theory, you could also use properties to change the status of a Thng, but this can be a problem when both an application and the web Thing itself want to edit the same property. This is where actions can help. Let’s draw a parallel to better grasp the concept: actions represent the public interface of a Thng and properties are the private parts. Much like in any programming languages, you can access the public interface, and whatever is private remains accessible only for privileged parties, like the instance itself or, in this case, the Thng. But limiting access to actions—that is, the public interface—also allows you to implement various control mechanisms for external requests such as access control, data validation, updating a several properties atomically, and the like.

The metadata about Thngs is represented using custom fields which are key-value pairs that can be used to describe static information about the Thng (e.g. color is a good candidate for a custom field).

Unlike properties, which are time series, custom fields are used to describe data that will not change frequently or whose history does not need to be stored.

Products, Applications, and Users

A Thng always should always be linked to a product which denotes the "type" of the device. For example, a smart thermostat Thng would be an instance of a Smart Thermostat product.

An application represents a mobile, desktop, web, or cloud client application that is used by an Application User to control the connected device. For example, using an Android/iOS native application to control a smart thermostat.

Anyone using an application to interact with a Thng needs to be authenticated and authorized, which is done via the Application Users API.


Create a Connected Washing Machine

EVRYTHNG provides a number of SDKs for various embedded platforms. You can connect your connected products with HTTP using our REST API, with MQTT, or with WebSockets thanks to our multiprotocol pub/sub broker.

In this section, we will go through the steps required to digitally connect a physical product to our Platform by using an embedded controller on the product. Connecting an embedded device to the EVRYTHNG platform means its functionality (commands) and real-time state (properties) are made accessible through standard Web technologies via our cloud. In this tutorial, we will create a web-connected washing machine by using the Intel Edison as embedded platform.

The washing machine will be accessible through the EVERYTHING API from any Web-enabled application such as your browser or a mobile phone.

At the end of this quick start, you will have:

  • A working project environment for connected products.
  • A Thng for the washing machine that the embedded board can connect to.
  • The ability to send actions to an Intel Edison board to turn its on-board led on or off.
  • A dashboard to monitor the state and the context of the Intel Edison board in real time according to location, time, action, and users.
  • A data analysis dashboard with features to visualise and navigate historical data.

This quick start includes sample code that you can use right away.


Create a Project

First, we need to create a project in your account. A project is a logical construct to organise your resources and applications. Projects are a way to specify security policies and limiting access and visibility of Thngs to only certain users and/or apps. For example, a user can access a Thng if they both share the same scope. In this quick start, the project scope is specified when a resource is added with the parameter ?project=[projectid] in the request URL.

So let's go ahead and create your first project as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/projects' \
  -d '{
    "name": "Embedded Devices",
    "description": "Project for the EVT embedded devices quickstart"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UfPNGt4qsVKaUDnHQ9AwHbma",
  "createdAt": 1441636268266,
  "updatedAt": 1441636268266,
  "name": "Embedded Devices",
  "description": "Project for the EVT embedded devices quickstart",
  "shortDomains": ["tn.gg"]
}

Add Resources

Resources are products, Thngs and action types. The Platform product resource represents a category of products.

Create a Product for the Washing Machine Model

In this example, the product is the specific washing machine model. In this scenario, we use the product to group Thngs according to their type and to store manufacture specific information related to that product. So, you can create a product for the washing machine within the scope of the project we created before as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/products?project=UfPNGt4qsVKaUDnHQ9AwHbma' \
  -d '{
    "name": "Intel Edison board",
    "description": "A Web-connected smart washing machine",
    "tags": [
      "WoT",
      "device",
      "washing machine"
    ],
    "photos": [ "https://software.intel.com/sites/default/files/managed/cd/8e/IoT_getstarted_edisonboard.png" ]
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UCsrm9nsseKaGtBXnBsYncXq",
  "createdAt": 1441636270255,
  "updatedAt": 1441636270255,
  "tags": ["WoT","device","washing machine"],
  "description": "A Web-connected smart washing machine",
  "name": "Intel Edison board",
  "photos": ["https://software.intel.com/sites/default/files/managed/cd/8e/IoT_getstarted_edisonboard.png"]
}

Create a Thng for the Washing Machine

The Thng in this example is the virtual representation of the connected product, which is a washing machine equipped with the Edison board. Create a new Thng, and set the product of the Thng to the previously created product. It provides the Intel Edison device with a unique digital identity.

The Thng also contains the device's properties which can be modified and queried through the EVRYTHNG API. Create the Thng in our project as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/thngs?project=UfPNGt4qsVKaUDnHQ9AwHbma' \
  -d '{
    "name": "Washing machine control unit",
    "product": "UCsrm9nsseKaGtBXnBsYncXq",
    "description": "Intel Edison controller",
    "tags": [
      "WoT",
      "device",
      "washing machine"
    ]
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UC8r39HP8B5wUXHHt9danbnq",
  "createdAt": 1441636270993,
  "tags": ["WoT","device","washing machine"],
  "updatedAt": 1441636270993,
  "name": "Washing machine control unit",
  "description": "Intel Edison controller",
  "product": "UCsrm9nsseKaGtBXnBsYncXq"
}

Create an Action Type to Set the State of LEDs

Actions are messages that can be sent by an app to a device. Usually, actions model the commands a device supports so that it can be interacted with from afar.

As properties should always represent the current state of a device, one can use an action to send a command to a device (which in turn may or may not update the properties of the device). Actions facilitate the design and development of loosely coupled component, in which each component manages its state and offers a stable interface to other components (which can be the actions it supports).

We will now create an action type that can turn an LED on or off.

You will have to create a new action type for each command you would like to send to your device, or each notification you would like your device to send (for example to start washing cycle, to notify when the wash cycle is finished, etc.).

Create the new _setLedStatus action type as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/actions?project=UfPNGt4qsVKaUDnHQ9AwHbma' \
  -d '{
    "name": "_setLedStatus",
    "description": "Turns the LED on or off",
    "tags": [
      "WoT",
      "device"
    ]
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UWsNmt4rsVpwGQBD4BshHcCk",
  "createdAt": 1441636269298,
  "updatedAt": 1441636269298,
  "tags": ["WoT","device"],
  "name": "_setLedStatus"
}

Authorize a Device

Thngs that represent devices require a Thng API key (sometimes also called a Device API key) to interact with the platform.

With a Device API key, the device can authenticate itself, change its Thng's properties, subscribe to actions from the platform and create new actions on itself.

You can generate an API key for this unique washing machine (by sending its Thng ID) as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/auth/evrythng/thngs' \
  -d '{
    "thngId": "UC8r39HP8B5wUXHHt9danbnq" 
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "thngId": "UC8r39HP8B5wUXHHt9danbnq",
  "thngApiKey": "p8FL14YQZEOvsOiIJQtlU5omleZkUH1uUiVSE0qi41f434IBqaUuYvlixy3yR6sid8MzyFSnSA1CFuhz"
}

Creating an Application

A project can contain zero or more applications. An application provides an Application API key. You can then use this API key to create a user which can then interact with the Thngs.

Create an application within your project as follows (note that the URL contains the Project ID):

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/projects/UfPNGt4qsVKaUDnHQ9AwHbma/applications' \
  -d '{
    "name": "Smart washing machine",
    "description": "A led-blinking smart washing machine",
    "tags": [
      "WoT",
      "device",
      "washing-machine"
    ],
    "socialNetworks": {}
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UWsN3tpw8B5w3QBDnBPYncke",
  "createdAt": 1441636272076,
  "updatedAt": 1441636272076,
  "name": "Smart Washing Machine",
  "description": "A LED-blinking smart washing machine",
  "appApiKey": "2FXSucyiLcICYBGUjcVZXOsiPF3iDy9SItmwXkX1Kqi09DBuimc9dhQO24GnD2Gvn3yRELhrOMXeqcMC",
  "tags": ["WoT","device","washing-machine"],
  "project": "UfPNGt4qsVKaUDnHQ9AwHbma",
  "socialNetworks": {}
}

Setting up the Development Environment

The embedded application for this quick start is written for Node.js. Install it on your Intel Edison board with Intel’s XDK IDE. This app uses the EVRYTHNG extended.js SDK and the EVRYTHNG MQTT plugin.

Create a New XDK IoT Project

Create a new empty project for Node.js in XDK and add a new file main.js. Install the node modules evrythng-extended (which is the EVRYTHNG JavaScript SDK, see more here), evrythng-mqtt and mraa.

"use strict";

var EVT = require('evrythng-extended'),
   mqtt = require('evrythng-mqtt'),
   mraa = require('mraa');

Connect to the EVRYTHNG Platform via MQTT

The application running on your washing machine controller will use the Thng ID and the corresponding Device API key. Note that application will use MQTT transparently by loading the MQTT plugin with EVT.use(mqtt);.

EVT.use(mqtt);

var device = new EVT.Device({
  apiKey: "p8FL14YQZEOvsOiIJQtlU5omleZkUH1uUiVSE0qi41f434IBqaUuYvlixy3yR6sid8MzyFSnSA1CFuhz",
  id: "UC8r39HP8B5wUXHHt9danbnq"
});

Subscribe to _setLedStatus Actions

In this example, clients exclusively change the device state through the _setLedStatus action and the device manages its state in the cloud itself.

When it starts, the device updates the ledStatus property in the platform to reflect the state of the physical LED on the device. A user can only change the LED status by sending a _setLedStatus action, and specifying the desired status of the LED in the action object payload (using customFields).

The device will then try change the state of the physical LED, and if successful it will update its ledStatus property. This way, the Thng in the cloud will always be consistent with the state of the physical device, as it is only modified by the application running on the washing machine.

(function evtWashingMachineController(evtDevice) {
  var led = new mraa.Gpio(13);
  led.dir(mraa.DIR_OUT);
  evtDevice.property("ledStatus").update(led.read());
  evtDevice.action("_setLedStatus").subscribe(function(action) {
    led.write(action.customFields.status);
    evtDevice.property("ledStatus").update(action.customFields.status);
  });
})(device);

Deploy the App and Send a _setLedStatus Action

Run the code on your Edison and send it a _setLedStatus action, passing the desired state as a custom field of the action as follows:

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/thngs/UC8r39HP8B5wUXHHt9danbnq/actions/_setLedStatus?project=UfPNGt4qsVKaUDnHQ9AwHbma' \
  -d '{
    "type": "_setLedStatus",
    "customFields": {
      "status": true
    }
  }'
HTTP/1.1 201 Created
Application/json

{
  "id": "UCsNKBkcPeKRG9BXnVPk2c8h",
  "createdAt": 1441641602854,
  "timestamp": 1441641602854,
  "customFields": {
    "status": true
  },
  "createdByProject": "UfPNGt4qsVKaUDnHQ9AwHbma",
  "thng": "UC8r39HP8B5wUXHHt9danbnq",
  "product": "UCsrm9nsseKaGtBXnBsYncXq"
}

Connected Web App

A generic example web app is available to serve as a basis for building apps that communicate with Thngs in the EVRYTHNG Platform. The interface is geared towards allowing you to manage connected devices that may have many properties, which can be updated from the app itself.

The app also allows you to create actions on the devices using any custom action types associated with the application the app is interacting with.

Check out the GitHub repository to learn more about using this app to manage EVRYTHNG Thngs and connected devices.

You can also switch between whether the action and property update requests go through the cloud API or a local THNGHUB gateway, if one is configured correctly in the app settings.

Connected Products