Sorry, too much content to display for current resolution.

Getting started

Welcome to the WolkSense Sensor Data Cloud, an IoT platform used for developing, testing and deploying your IoT ideas!
This guide will get you started in connecting your devices to the WolkSense Sensor Data Cloud and building applications for them.

Terminology

Before you start, you should make yourself familiar with the common terms used in the documentation and API’s

Core concepts

Device

In WolkSense, device represents physical device which connects to the cloud through Internet via MQTT protocol. It is represented in the system by its serial number and is closely related to a point; effectively acting as a physical source of the data for it.

Point

Point represents a point of measurement. It describes what the measurements we are collecting mean (For example you can name the point by location - Room 15, Living Room, Basement) and interval at which the data is collected (heartbeat). Each point has a set of feeds.

Feed

Feed is a representation of a single type of measurement on a single point. Feed describes a specific sensor measurement by defining its type (temperature, humidity etc…) and defines high/low alarms for measured values. Value of a feed is the last reported measurement of a given type on a given point and its recent trend (rising, falling).

Support concepts

Access/Refresh Token

Access token is standard method of authentication when making an https request on a server system. It has a limited period of validity and can be obtained through sign in process by supplying username/password combination or by using a refresh token which is used to replace the expired access token. Access token lasts for a day, while refresh token is valid for a month or until used to obtain new access token.

Serial number / Password

Serial number identifies the device to our platform, and password authenticates it. For WolkSensor™ device this combination is pre-supplied and serial number can be read from the back of the device. Otherwise, a unique serial number / password combination can be obtained for your devices through Web API. This combination is required when your device connects to WolkSense to ensure authenticity of the data.

Username / Password

Username/Password combination is used to obtain access token. Username/Password combination is registered in the system through sign up process.

Web API

Sign in

signIn

POSThttps://api.wolksense.com/api/signIn

Headers

Content-Type: application/json

			
	"Request": {
             "email": String,
	     "password": String
         }
    	"Response": {
	     "accessToken": String,
	     "accessTokenExpires": DateTime,
	     "email": String,
	     "refreshToken": String,
	     "refreshokenExpires": DateTime,
	     "role": Role
	 }
	    
         ----------------------------------------------------------------------
         Role = "ADMIN"
			
		

Devices

getDeviceStatus

GEThttps://api.wolksense.com/api/v2/devices/{serialNumber}/activation_status

Headers

Content-Type: application/json

Authorization: token

			
	"Response": {
	    "activationStatus": ActivationStatus
	}
		
	--------------------------------------------------------------------------	
	ActivationStatus = "ACTIVATED", "BELONGS_TO_OTHER_USER" or "NOT_ACTIVATED"
			
		

generateSerial

GEThttps://api.wolksense.com/api/v3/devices/random_serial?type=

Headers

Content-Type: application/json

Authorization: token

			
	params: 
	  "type": Type
	
       
        "Response": {
	  "serial": String
	}
         
         ----------------------------------------------------------------------
         Type = "HEXIWEAR", "WOLKSENSOR", ""
         String = serialNumber
			
		

activateDevice

POSThttps://api.wolksense.com/api/v2/devices/{serialNumber}

Headers

Content-Type: application/json

Authorization: token

			
	"Request": {
             "name": String
         }
    	"Response": {
	     "name": String,
	     "pointId": Int,
	     "password": String
	 }
			
		

deactivateDevice

DELETEhttps://api.wolksense.com/api/v2/devices/{serialNumber}

Headers

Content-Type: application/json

Authorization: token

Feeds

getFeedReadings

GEThttps://api.wolksense.com/api/v2/feeds/{feedId}/readings?from=Long&to=Long&aggregationLevel=AggregationLevel

Headers

Content-Type: application/json

Authorization: token

			
	 params: 
		"from": Long,
		"to": Long,
		"aggregationLevel": AggregationLevel
	 
       
        "Response": [
             {
		"t": Long,
		"a": String,
    		"l": String,
    		"h": String
             }
         ]
         
         ----------------------------------------------------------------------
         AggregationLevel = "HALF_HOUR", "ONE_DAY", "ONE_MINUTE" or "SIX_HOURS"
      	 Long = time in milliseconds
         a = average value, l = min.value (low), h = max.value (high)
			
		

updateFeedSettings

PUThttps://api.wolksense.com/api/v2/feeds/settings

Headers

Content-Type: application/json

Authorization: token

			
	"Request": {
             "settings": [
                 {
                     "id": Int,
                     "order": Int
                 }
             ]
          }
			
		

Points

getPoints

GEThttps://api.wolksense.com/api/v4/points

Headers

Content-Type: application/json

Authorization: token

			
	"Response": [ 
           {
             "name": String,
             "id": Int,
             "deviceSerial": String,
             "firmwareVersion": String,
             "currentBatteryState": Int,
             "activationTimestamp": Long,
             "deviceState": DeviceState,
             "batteryState": Int,
             "heartbeat": Int,
             "lastReportTimestamp": Long,
             "owner": Owner,
             "feeds": [
              {
                     "id": Int,
                     "readingType": String,
                     "currentValue": Double,
                     "alarmState": AlarmState,
                     "alarmHigh": Double,
                     "alarmHighEnabled": Boolean,
                     "alarmLow": Double,
                     "alarmLowEnabled": Boolean,
                     "trend": Trend,
                     "enabled": Boolean,
                     "visible": Boolean,
                     "order": Int
	       }
	     ],
	     "actuators": []
	   }
         ]
         
        -----------------------------------------------------
        DeviceState = "CONNECTED", "DEACTIVATED" or "OFFLINE"
        AlarmState = "HIGH", "LOW" or "NORMAL"
        Trend = "FALLING", "RISING" or "STEADY"
        Owner = "SELF"
			
		

getPoint

GEThttps://api.wolksense.com/api/v4/points/{id}

Headers

Content-Type: application/json

Authorization: token

			
        "Response": {
             "name": String,
             "id": Int,
             "deviceSerial": String,
             "firmwareVersion": String,
             "currentBatteryState": Int,
             "activationTimestamp": Long,
             "deviceState": DeviceState,
             "batteryState": Int,
             "heartbeat": Int,
             "lastReportTimestamp": Long,
             "owner": Owner,
             "feeds": [
              {
                     "id": Int,
                     "readingType": String,
                     "currentValue": Double,
                     "alarmState": AlarmState,
                     "alarmHigh": Double,
                     "alarmHighEnabled": Boolean,
                     "alarmLow": Double,
                     "alarmLowEnabled": Boolean,
                     "trend": Trend,
                     "enabled": Boolean,
                     "visible": Boolean,
                     "order": Int
	       }
	     ],
	     "actuators": []
	   }
	   
       -----------------------------------------------------
       DeviceState = "CONNECTED", "DEACTIVATED" or "OFFLINE"
       AlarmState = "HIGH", "LOW" or "NORMAL"
       Trend = "FALLING", "RISING" or "STEADY"
       Owner = "SELF"
			
		

getUnreadMessagesForPoint

GEThttps://api.wolksense.com/api/v4/points/{pointId}/messages?from=Long&to=Long

Headers

Content-Type: application/json

Authorization: token

			
	params: 
	     "from": Long,
	     "to": Long,
	 
      
        "Response": [
           {
             "id": Int,
             "content": String,
             "timestamp": Long,
             "collapseKey": String,
             "readingType": String,
             "details": String
           }
         ]
         
        ---------------------------
        Long = time in milliseconds
			
		

acknowledgeUnreadMessagesForPoint

PUThttps://api.wolksense.com/api/v4/points/{id}/messages

Headers

Content-Type: application/json

Authorization: token

deletePoint

DELETEhttps://api.wolksense.com/api/v4/points/{id}

Headers

Content-Type: application/json

Authorization: token

updatePoint

PUThttps://api.wolksense.com/api/v4/points/{id}

Headers

Content-Type: application/json

Authorization: token

			
	 "Request": {
             "name": String,
             "heartbeat": Int,
             "feeds": [
                 {
                     "id": Int,
                     "alarmHigh": Double,
                     "alarmHighEnabled": Boolean,
                     "alarmLow": Double,
                     "alarmLowEnabled": Boolean,
                     "enabled": Boolean
                 }
             ]
      	 }
			
		

MQTT API

MQTT Support

WolkSense Sensor Data Cloud uses MQTT protocol to exchange data with devices. MQTT is a lightweight, subscription based protocol used as a de facto standard for IoT communication between server and clients. More info about MQTT may be found here.

Connecting to MQTT broker

WolkSense MQTT broker is hosted on wolksense.com on port 8883 and accepts SSL/TLS encrypted connections. Username/password authentication is used to identify MQTT clients and grant them access to specific topics.

In order to connect IoT device (i.e. MQTT client) to the broker, the device should be first registered on WolkSense Sensor Data Cloud. Device registration is performed via RESTful Web API call, during which, credentials for MQTT broker are obtained. Credentials consist of username and password, where username maps to device serial number. Both device serial number and password are generated and returned in the response from RESTful Web API.

Client libraries

To register devices and publish readings to WolkSense Sensor Data Cloud you can use Java, Python and C++ libraries available at GitHub.

WolkConnect - Java

WolkConnect - Python

WolkConnect - C++

Publishing messages

When the client (IoT device) is connected to the broker messages may be published to topic:

sensors/{serialNumber}

Where {serialNumber} is serial number of the device that is publishing message.

WolkSense Sensor Data Cloud delivers response on:

config/{serialNumber}

Typically, IoT devices publish messages with readings data while WolkSense Sensor Data Cloud responses contain different configuration parameters for devices, such as real time clock synchronisation, heartbeat and alarms.
See scenario examples chapter for details.

mqtt-sheme

Messages format

Messages content is formatted in plain ASCII. Numbers are formatted without decimal point.

Reading types

All reading types are formatted as:

readingType = Type ":" Value

Where Type and Value are defined as:

  Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
  Type = "T" | "P" | "H" | "LT" | "STP" | "BPM" | "KCAL" | "ACL" | "MAG" | "GYR" | "GEN"
  Value = ("+" | "-") {Digit}
		

Below are specifications for each reading type with examples.

table-img

Commands

WolkSense Sensor Data Cloud recognizes the following commands.

table-img

Scenario examples

Scenario 1

IoT device connects to MQTT broker and publishes list of readings.

RTC 1463400000;READINGS R:1463400000,T:+243,P:+10031,H:+374;

The message consists of real time clock timestamp (RTC) and readings values (READINGS) for temperature = 24.3 Celsius degrees, pressure = 1003.1mbar, humidity = 37.4%.

WolkSense sensor data cloud response may be:

RTC 1463400000;HEARTBEAT 5; ALARM T:190,OFF|P:OFF,OFF|H:OFF,800;

IoT device should set internal heartbeat to 5 minutes and alarms for temperature = (low to 19.0 Celsius degrees, high to OFF), pressure = (both low and high alarms to off), humidity = (low alarm to off, high alarm to 80.0%).

Scenario 2

IoT device connects to MQTT broker and publishes list of readings for more than one timestamp. Imagine that client collects data each minute and sends them to the broker each 5 minutes.

		
 RTC 1463400060;READINGS R:1463400000,T:+243,P:+10041,H:+374|READINGS
 R:1463399940,T:+233,P:+10031,H:+364|READINGS
 R:1463399880,T:+223,P:+10021,H:+354|READINGS
 R:1463399820,T:+213,P:+10011,H:+344|READINGS
 R:1463399760,T:+203,P:+10001,H:+334;
 		
		

The message consists of real time clock timestamp (RTC) and readings values (READINGS) for five timestamps offset by one minute (60 seconds).

WolkSense sensor data cloud response may be:

RTC 1463400060;HEARTBEAT 5; ALARM T:190,OFF|P:OFF,OFF|H:OFF,800;

IoT device should set internal heartbeat to 5 minutes and alarms for temperature = (low to 19.0 Celsius degrees, high to OFF), pressure = (both low and high alarms to off), humidity = (low alarm to off, high alarm to 80.0%).