Copyright 2015 Haltian Ltd. All rights reserved. Haltian and Thingsee are registered trademarks of Haltian Ltd.

Transcription

1 Thingsee Engine API Version 01.00, Copyright 2015 Haltian Ltd. All rights reserved. Haltian and Thingsee are registered trademarks of Haltian Ltd. Haltian Ltd reserves all ownership rights for the documentation. This document and all of its contents are provided as-is. Redistribution is NOT permitted. Permission to use, copy, modify, and/or distribute this document for any purpose is not permitted without an approval of Haltian Ltd representative. Introduction Thingsee Engine API is a collection of different messages and data models that are used by Thingsee device to connect and communicate with different cloud services. This specification does not specify any REST API or other protocols for communication. Instead, it defines the payload that needs to be sent between cloud and device to support all Thingsee features. There are no strict protocols, REST APIs or other transport requirements for these APIs. It is up to Thingsee Connector implementation to implement communication as requested by cloud service; Thingsee Engine API is built as a data definition using JSON structures, and the only requirement for cloud server is to provide and handle these data structures as defined in this API document. Thingsee will support a few ready-made connectors for selected cloud services, and those can be used as is, or as a reference implementation for other cloud services.

2 API overview Thingsee Property (API) defines message structures for exchanging deviceand cloud-specific settings between communicating parties. A device will use this API to describe its properties and available sensors to cloud. A cloud will send its properties to a device, usually containing user account information, urls, protocols and other credentials. Thingsee Profile (API) defines purposes for Thingsee device. This data structure is a description of state-machine with user-defined events, thresholds and actions. Thingsee device behaviour and use cases can be fully defined by changing the device profile without any need to modify actual device software. Thingsee Event (API) is the container for all sensor data sent by a device. Thingsee (Purpose) Engine is the run-time for Thingsee intelligence, and it uses a profile to create a behaviour model and a simple state-machine functionality. Thingsee Connector is an extension to Thingsee (Purpose) Engine, and its responsibility is to handle all communications between the device and the cloud. This component makes sure that all the data is transferred to the correct web APIs, and that communication protocols and initiative functions are taken care of.

3 Thingsee Connector is cloud service specific and it should be the only component that needs changes when integrating Thingsee to any cloud server. Thingsee Property Device Property A device will send the following data structure to a cloud service to communicate its properties and capabilities. This data block is static and transferred to a web backend server during the device initialisation and/or pairing process. The cloud server should store this data for further communication and management. The main purpose of this data is to inform backend (especially Thingsee Creator applications) about the features, attributes and functionality of the device. These properties are the key input when device profile (purposes) is created. { "device" : { name : String, "swname": String, "swversion": String, hwversion : String, "serial : String, variant : { primarycolor : String, secondarycolor : String, customername : String, productfamily : String } }, "module" : [{ "moduleid": String, "modulename": String, "senses": [{

4 } }] "sid": String, min : Number, max : Number, mininterval : Number }] Device object contains basic information about the device and Thingsee version. This version information is used when deploying new firmware versions as firmware-over-the-air (FOTA) updates. Module object is the most important part for purpose development. This describes all the sensors (senses) available within a device. The senses are the key components used for purpose programming for the device. In the future, Thingsee will support 3rd party HW modules via hardware buses or Bluetooth connection, and therefore this descriptor already supports multiple modules and their independent senses. Parent object Object Mandatory Description device swname No Software description e.g. Thingsee B2.0 device swversion No Software version information e.g device hwversion No Hardware version information e.g. B1.5_0302 device serial Yes Product serial number module moduleid No Device originated identifier for a sensor module subsystem. Device defined name for a

5 module modulename No module e.g. ACME Bluetooth sensor or ThingseeOne senses sid Yes Sensor identifier as specified in 5.2 senses min No Minimum value that can be read from the sense senses max No Maximum value that can be read from the sense senses mininterval No Shortest interval between reading values from the sense Device property configuration stored in a file format is referred as device.jsn Cloud Property Applications or cloud can upload the following information onto a device. Typically this data is something that the end-user will configure through a mobile app or web dashboard. { "connections" : { "wificonnections": [{ "connectionid": Number; "ssid": String, "password": String, "encryption": String }], "cellularconnections" : [{ "connectionid": Number, "accesspointname": String, proxyaddress : String, proxyport : String,

6 username : String, password : String, mobilecountrycode : String, mobilenetworkcode : String, authtype : String, enableroaming : Boolean }] }, "connectors" : [{ "connectorid": Number, "connectorname": String, api : String, "protocol": String, host : String, "port": Number, uuid : String, token : String, }], cloudproviderx : { appid : String, appkey : String, accesstoken : String, thingid : String }, cloudprovidery : { somefield : String, otherfield : String }, cloudproviderz : { somefield : String, otherfield : String }

7 sms : { min_interval_minutes : Number, max_per_day : Number } } Connectivity object contains user-specific credentials and parameters that are needed for connecting e.g. to a Wi-fi network. This data will be stored as encrypted data in a device. Connectors object describes configured cloud backend connection(s) within a device firmware. Typically single device will implement only one connector because of limited resources within a device. Parent object Object Mandatory Description connections wificonnections No Object for wifi configuration wificonnections connectionid Yes Index number of connection configuration generated outside device wificonnections ssid Yes Wi-fi network SSID wificonnections password No Wi-fi network password wificonnections encryption No Wi-fi network encryption settings connections cellularconnections No Object for cellular

8 configuration cellularconnections connectionid Yes Index number of connection configuration generated outside device cellularconnections accesspointname Yes Name of the cellular operator access point e.g. Internet cellularconnections proxyaddress No The address of http proxy to use cellularconnections proxyport No The port for proxyaddress cellularconnections username No Access point username cellularconnections password No Access point password cellularconnections mobilecountrycode Yes The mobile country code for cellular subscription cellularconnections mobilenetworkcode Yes The mobile network code for cellular subscription cellularconnections authtype No Authentication type PAP,

9 CHAP cellularconnections enableroaming No Enable roaming connectors connectorid No Index number of connector configuration generated outside device connectors connectorname No Name of the connector setup e.g. Haltian Web Proxy connectors token No Connector token connectors protocol Yes Connector protocol e.g. http, https, mqtt, coap connectors url Yes Address of the cloud service base domain connectors port Yes Port number for cloud service sms min_interval_minutes No Minimum interval in minutes between to consecutive sms messages

10 sms max_per_day No Maximum number of sms messages that can be sent per day Cloud property stored in a file format is referred as cloud.jsn Thingsee Profile A profile is the core of Thingsee intelligence. It defines the behaviour, i.e. purpose, of the Thingsee device; states, sensors, thresholds, events and actions. ThingseeEngine is the run-time for profile and it is delivered as a binary component in Thingsee SW release. ThingseeEngine can run only one profile at a time, but single profile can contain multiple different purposes. Purpose can be thought as a single usecase, such as a pet-tracking purpose, door-activity purpose, thermometer purpose, etc. A single profile can contain multiple purposes and make logic switch between purposes based on events happening in another purpose. For example, Thingsee device can act as thermometer (purpose) until it is changed to act as pet-tracker by mobile app. This way a single device can have multiple built-in purposes without any need to download a new purpose every time user wants to change device behaviour. A profile is constructed by following these rules: ThingseeEngine will have only one Profile One Profile can contain multiple Purposes, but only one purpose is active One Purpose can contain multiple States, but only one state is active One State can contain multiple Tasks and any task can trigger an action (OR operand) One Task can contain multiple Senses and all Senses must be true to trigger an event (AND operand) One Sense contains thresholds

11 A state can be changed when any of the state events is true (OR operand). An event is true when all of its thresholds are true (AND operand). { profile : { apiversion : String, pid : String, name : String, initpuid : Number purposes : [{ puid : Number, name : String, "initstid": Number "states": [{ "stid": Number, name : String, "isglobal": Boolean, "events": [{ "evid": Number, name : String, "eventlog": Boolean, "actions": { sms : { text : String, phonenumber : [Array of Strings] }, cloud : { "sendevent": Boolean, sendpush : Boolean, sendlog : Boolean, host : String, port : Number, api : String

12 }, engine : { "gotostid": Number, "gotopuid": Number }, display : { "showtext": String, } }, "causes" : [{ "sid": Number, "orderid": Number, "senselog": Boolean, measurement : { log : Boolean, interval : Number, count : Number }, threshold : { count : Number, negate : Boolean, relative : Boolean, decimalacc : Number }, "thresholds": { "isoneof": [Array of Numbers], "isgt": Number, "islt": Number, "isnotin": [Array of Numbers], "isany": Boolean, isinsidegeo : [Array of Numbers] } }]

13 } } }] }] }] Parent object Object Mandatory Description profile apiversion Yes Version information of implemented Thingsee Engine API e.g profile pid No Cloud generated profile identifier profile name No Name of the profile. This is created by app, and not relevant for device sw. profile initpuid Yes Initial purpose where the ThingseeEngine will be started purposes puid Yes Index number for purpose. Defined by app. purposes name No Name of the purpose. Used by app and not relevant for ThingseeEngine purposes initstid Yes Initial state where the ThingseeEngine will be started

14 states stid Yes Index number for state. Defined by app. states name No Name of the state. Defined by app, not relevant for ThingseeEngine states isglobal No Set to TRUE if state must be active always within this purpose events evid Yes Index of event. Defined by app. events name No Name of the event. Defined by app, not relevant for ThingseeEngine events eventlog No Set to TRUE if events must be logged to device memory events actions Yes Defines the actions that must be processed when thresholds are true. actions sms No Configuration of SMS action sms text Yes Content of SMS to be sent sms phonenumber Yes phonenumber where the SMS should be sent in E.164 format, ie

15 actions cloud No Configuration of cloud action cloud sendevent No Set to TRUE if ThingseeEngine must send Thingsee Event to cloud cloud sendlog No Set to TRUE if ThingseeEngine must flush log content to cloud cloud sendpush No Set to TRUE if cloud server should send push notification for Thingsee Event. Note that this requires that sendevent is also TRUE. actions engine No Set engine control configuration engine gotostid No Sets Thingsee Engine to another state engine gotopuid No Sets Thingsee Engine to another purpose actions display No Configuration of user interface actions (if device has display) display showtext Yes Content of text to be shown at UI events senses Yes Defines the configuration of thresholds and sensors

16 senses sid Yes Sense identifier to be monitored senses orderid No Defines the order index in case the sense must happen in some order senses senselog No Set to TRUE if senses are logged to device memory senses measurement Yes Defines the frequency and other parameters how the sense is read. measurement log No Set to TRUE if all sense readings are stored to device memory. This object is not valid for sensors using HW interrupts. measurement interval Yes Interval of sense reading defined as milliseconds measurement count No Number of sense reading after sense becomes TRUE (regardless of thresholds). Defaults to 0. This object is not valid for sensors using HW interrupts. threshold count Yes How many times threshold must be TRUE to set sense to TRUE threshold negate No If TRUE, the thresholds setting will be inversed

17 threshold relative No If TRUE, the thresholds will be handled as a relative value to a first reading value. Otherwise thresholds are handled as absolute values. threshold decimalacc No Accuracy of thresholds. Value 2 equals x.xx thresholds isoneof No is TRUE if sense value is one of numbers thresholds isgt No is TRUE if value is greater than threshold thresholds islt No is TRUE if value is less than threshold thresholds isnotin No is TRUE if value is not any of numbers thresholds isany No is TRUE always. This is useful for events where measurement interval is used as a trigger and fired every time thresholds isinsidegeo No Set to TRUE if location sense is inside specific geolocation coordinates array (polygonal geofence). Even number with minimum length of 6. Using invert sense can be used to map location outsidegeo with value set to false

18 Thingsee Event Sensor data is always sent as an event. An event can be one-time or continuous and it may be real-time or sent as logged history data. Thingsee device is capable of buffering events to a memory card, and occasionally flushing events to cloud server when network connection is available. Sense object is an array of sensors ids and values, and there can be optionally information about engine reason of the event. JSON structure for Thingsee Event is defined as: events : [{ engine : { pid : String, puid : Number, stid : Number, evid : Number, ts : Number }, senses : [{ sid : String, val : String OR Number (integer or ), ts : Number }] }] The root of the JSON data contains only senses-object. Senses is an array of sensor-data values containing the following data Parent object Object Mandatory Description events engine Yes Information about engine status

19 events senses Yes Information about the actual senses and values senses sid Yes Identifier for sensor data. senses val Yes Actual sensor value. senses ts No Sensor value UTC timestamp as number of milliseconds after the UNIX epoch. If timestamp is not sent within a sense, then engine -> ts will be used. engine pid Yes Currently active profile ID engine puid Yes Identifies which purpose was run when the event was triggered. engine stid Yes Identifies which state was active when the event was triggered. engine evid Yes Identifies which event was triggered. engine ts Yes Timestamp when the event was triggered (determined by engine). Thingsee Ping Event is a special purpose event, and sent only when profile has been changed. events : { engine : { pid : String } } SenseID

20 SenseID is global constant to identify different sensors and their attributes. These constants are extendable, and new sensors, units and attributes will be added based on need. SenseID format SenseID is string-formatted 32-bit hexadecimal identifier. This format has been chosen to make it easy in Thingsee to handle various different sensors and their data, and the string-format is used just as a transport within JSON structure. SenseID 0xAABBCCDD is constructed using the following schema Part Description AA Reserved for future use. Defaults to 00. BB Group ID identifies the logical group where the data property belongs. CC Property ID identifies exact sensor/data information as a single attribute. E.g. latitude and longitude are divided into two different SenseIDs. DD Index number within a device. This allows single device to report up to 256 similar data properties e.g. 256 battery statuses from a device hub and its sub-network. Available SenseIDs All values will be returned from a device as given by sensor. Accuracy of a specific property is determined by sensor hardware component, hardware drivers and/or libraries within device OS. Group GroupID PropertyID Property Unit Datatype location 0x01 0x01 latitude, signed degrees

21 location 0x01 0x02 longitude, signed degrees location 0x01 0x03 altitude, signed meters location 0x01 0x04 accuracy meters location 0x01 0x05 Is inside geofence boolean boolean speed 0x02 0x01 gps speed m/s energy 0x03 0x01 Battery full capacity mah energy 0x03 0x02 Current battery level % Current energy 0x03 0x03 battery V voltage energy 0x03 0x04 Is connected to charger boolean boolean orientation 0x04 0x01 Heading degrees degrees orientation 0x04 0x02 Yaw, signed degrees orientation 0x04 0x03 Pitch, signed degrees orientation 0x04 0x04 Roll, signed degrees Longitudinal acceleration 0x05 0x01 acceleration, g signed

22 Lateral acceleration 0x05 0x02 acceleration, g signed Vertical acceleration 0x05 0x03 acceleration, g signed acceleration 0x05 0x04 Impact, no direction g environment 0x06 0x01 Temperature, signed C environment 0x06 0x02 Humidity % environment 0x06 0x03 Ambient light lux environment 0x06 0x04 Air pressure hpa Magnetic environment 0x06 0x05 field, mgauss longitudinal environment 0x06 0x06 Magnetic field, lateral mgauss environment 0x06 0x07 Magnetic field, vertical mgauss Is power hw-keys 0x07 0x01 button boolean boolean pressed Is proximity hw-keys 0x07 0x02 button boolean boolean pressed

23 Cloud initiated actions Cloud server may include system_actions to any response sent back to device. It is expected that device will read and process that information. A cloud server will include system_actions information as long as actions are valid and device has not processed them. Response may contain the following JSON structure { } status : Number, systemactions : [{ updatefirmware : { version : String, url : String }, updateprofile : { pid : String, ts : Number }, rundiagnostics : { } }] Where status is Status value Define Description 0 TSCLOUD_OK Successful operation 1 TSCLOUD_ERR_GENERIC Error, generic error. No detailed reason known.

24 2 TSCLOUD_ERR_DATA Device has sent invalid or corrupted data. System actions object is an array of action objects that cloud service expects the device to handle. The nature of Thingsee device is offline use, and therefore this mechanism has been created to initiate specific device-side functions as soon as a device comes back online. Device actions are independent from status field. A cloud may send an array of actions even though the actual processing of previous request has failed with some error code. Firmware update Each Connector is responsible for initiating firmware update procedure whenever it has received indication of a new firmware version. Connector itself does not need to perform the actual firmware update, but it must act as an initiator for the process and handle firmware location (url) configuration and other initiative actions on behalf of the actual component that is responsible for the final flashing procedure. Cloud service must host and support Thingsee FOTA implementation more detailed FOTA specification will be added in later versions. Download new profile A Connector can implement Profile download functionality in case device needs to update its purpose remotely. Profile download (REST) API and communication protocol may be cloud-specific, but the data structure should follow Thingsee Profile definition. Change history Version Date Description This is 1.0 version of the API