SiteWhere: An Open Plat­form for Con­nected De­vices

SiteWhere de­liv­ers a com­plete man­age­ment sys­tem to help users avoid per de­vice charges by SaaS op­er­a­tors. It con­nects de­vices us­ing MQTT, AMQP, STOMP and other pro­to­cols, and de­vices can be added through self-reg­is­tra­tion, REST ser­vices or in batches. It

OpenSource For You - - Contents -

SiteWhere is an open plat­form for mon­i­tor­ing and con­trol­ling IoT de­vices and stor­ing de­vice data. It is li­censed un­der CPAL 1.0 and can be de­ployed as an on-premise so­lu­tion with com­plete free­dom and scal­a­bil­ity, which elim­i­nates the per de­vice or per data pric­ing by SaaS providers. It can also be de­ployed in a bare metal cloud en­vi­ron­ment for pub­lic ac­cess. It comes with ad­vanced mul­ti­ple ten­ant ar­chi­tec­ture to run var­i­ous IoT ap­pli­ca­tions in a sin­gle server in­stance. It in­te­grates with proven soft­ware and ser­vices for the en­hanced en­ter­prise needs of con­nected de­vices. This ar­ti­cle fa­mil­iarises you with the plat­form, fo­cus­ing on de­vice com­mu­ni­ca­tion us­ing JSON pay­loads over MQTT and on avail­ing plat­form ser­vices us­ing REST APIs.

Ar­chi­tec­ture and fea­tures

The core plat­form of the server is based on Spring Boot from v1.7.0 and comes with an em­bed­ded Tom­cat server in re­cent ver­sions, but you can still build the Web Ap­pli­ca­tion Archive (WAR) file from sources, and de­ploy it in a custom or vanilla ver­sion of the Tom­cat server. It comes with mul­ti­te­nancy sup­port from v1.2.0, each ten­ant en­gine is iso­lated, hav­ing its own data stor­age and pro­cess­ing chan­nels. It uses Mon­goDB for the de­fault data store, with SiteWhere as the core data­base and iso­lated data­bases for each of the ten­ants, with ten­ant-xxxx nam­ing. De­vices can com­mu­ni­cate us­ing the JSON for­mat or Google Pro­to­col Buf­fers (Pro­to­buf) over MQTT trans­port, and REST APIs are of­fered to avail plat­form ser­vices.

Each ten­ant de­vice is placed in a col­lec­tion, known as a site, to clus­ter the lo­ca­tion-aware de­vices. This en­ables mon­i­tor­ing of all events at the site level as well as the de­vice level. On boot­strap, a de­fault ten­ant en­gine is cre­ated with Con­struc­tion Site, ini­tially. De­vices can be kept un­der de­vice groups as log­i­cal units; these can as­so­ciate with de­vice spec­i­fi­ca­tions as per com­mon hard­ware fea­tures, and as­so­ciate with as­sets for real world map­ping.

Components and in­te­gra­tion

SiteWhere makes use of the fol­low­ing pop­u­lar open

source so­lu­tions and ex­ter­nal ser­vices— a few for in­ter­nal components and some for en­riched in­te­gra­tion sup­port with inbound and out­bound event pro­cess­ing.

Mon­goDB as the de­fault data store

Mosquitto as the MQTT bro­ker (even though HiveMQ is men­tioned in the doc­u­men­ta­tion)

Ac­tiveMQ, Rab­bitMQ for rich pro­to­col sup­port like AMQP, STOMP, etc.

Eclipse Cal­i­fornium for CoAP mes­sag­ing

In­fluxDB for time se­ries data and Grafana for vi­su­al­i­sa­tion HBase for distributed clus­ter­ing sup­port for de­vice events Ha­zle­cast, an in-me­mory data grid for ex­ter­nal event pro­cess­ing

Mule­soft Any Point Plat­form for ESB func­tion­al­ity

Azure Event Hub and Ama­zon SQS client li­braries for event for­ward­ing

WSO2 Sid­dhi for Com­plex Event Pro­cess­ing (CEP) WSO2 Iden­tity Server for as­set man­age­ment

Apache Spark for stream­ing an­a­lyt­ics

Apache Solr for in­dex­ing and search­ing de­vice events Twilio client for SMS alerts over the cloud

Map­ping de­vices with Ma­gento prod­ucts as as­sets through the com­mu­nity edition

It can also com­mu­ni­cate with ex­ter­nal cloud ser­vices like for ex­ter­nal mes­sag­ing and Ini­tialS­tate for ad­vanced data vi­su­al­i­sa­tion. It comes with an add-on for OpenHAB per­sis­tence sup­port and for con­trol­ling back de­vices via out­bound events.


In­stal­la­tion of SiteWhere is very sim­ple, with few de­pen­den­cies. In­stall OpenJDK 1.8, Mon­goDB and any MQTT bro­ker like HiveMQ or Mosquitto as de­pen­den­cies. Start Mon­goDB and MQTT bro­ker. Down­load the tar­ball of the lat­est sta­ble re­lease (v1.9.0 at present), ex­tract it to a suit­able lo­ca­tion, say /opt, then switch to the ex­tracted di­rec­tory, i.e., /opt/site­hwhere-server-1.9.0 and ex­e­cute the script bin/ To cus­tomise the server port, edit conf/ap­pli­ca­tion. prop­er­ties and un­com­ment the line server.port=8080.

Build­ing from sources

If you want to build SiteWhere from sources, check out the lat­est branch, say SiteWhere-1.10.0 or master from github. com/sitewhere/sitewhere.git and run the fol­low­ing com­mands.

To cre­ate a Web ap­pli­ca­tion archive (WAR) file, which can be de­ployed on a Tom­cat-like server, type:

gra­dle clean war

To gen­er­ate a stand­alone archive with an em­bed­ded server, sim­i­lar to the down­loaded tar­ball, use the fol­low­ing com­mand:

gra­dle clean serverTar Col­lect the gen­er­ated WAR file or tar file from the build/ dis­tri­bu­tions sub-di­rec­tory.

Run­ning SiteWhere in a Docker con­tainer

You can even run SiteWhere in a Docker con­tainer, for which you can check out the source code of any re­cent ver­sion, nav­i­gate to sitewhere-docker/stand­alone/1.8.0, and re­place the Ubuntu ver­sion 14.04 with 16.04 in Dock­er­file for bet­ter pack­age sup­port. Run the fol­low­ing com­mand to build the im­age:

docker build -t sitewhere/stand­alone:1.8.0 .

To launch the con­tainer for the built im­age, use the fol­low­ing com­mand:

docker run -p 8080:8080 -p 1883:1883 -p 61623:61623\ --name mysite­where sitewhere/stand­alone:1.8.0

To cus­tomise the port, launch the shell us­ing the fol­low­ing com­mand, switch to /opt/sitewhere/conf and edit ap­pli­ca­tion. prop­er­ties as men­tioned above:

docker exec -it mysite­where /bin/bash

If SiteWhere doesn’t start man­u­ally, launch the server as fol­lows:

docker exec -it mysite­where /opt/sitewhere/bin/

SiteWhere can also be de­ployed on cloud en­vi­ron­ments like Ama­zon EC2 and Mi­crosoft Azure for pub­lic ac­cess.

The first steps

You can ac­cess the HTML5 based Ad­min in­ter­face on the URL path /sitewhere/ad­min of the cho­sen host and port. An in­ter­ac­tive REST in­ter­face based on Swag­ger is avail­able on the path /sitewhere. For ex­am­ple, if the server is in­stalled on

the same ma­chine and run­ning on port 8080, ac­cess the ad­min in­ter­face by us­ing lo­cal­host:8080/sitewhere/ad­min and the REST in­ter­face us­ing lo­cal­host:8080/sitewhere. The de­fault cre­den­tial for both the in­ter­faces is ad­min:pass­word.

De­vice events

SiteWhere sup­ports the fol­low­ing de­vice events through the MQTT pro­to­col us­ing JSON or Google’s Pro­to­buf for­mat. In this ar­ti­cle we’ll use the JSON for­mat and pub­lish the pay­loads to the MQTT topic SiteWhere/in­put/json as per the ten­ant con­fig­u­ra­tion.

Reg­is­tra­tion: Any de­vice should be reg­is­tered ini­tially by pub­lish­ing the fol­low­ing JSON pay­load: { “hard­wareId”: “123-MyRpiSense-4567890”,

“type”: “Regis­terDe­vice”,

“re­quest”: {

“hard­wareId”: “123-RpiSense-4567890”, “spec­i­fi­ca­tionTo­ken”: “xxx­xx­xx­xx­xxxxxx”, “siteTo­ken”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” } };

Here hard­wareId can be any unique value; siteTo­ken iden­ti­fies the pre­ferred site, say con­struc­tion site, and spec­i­fi­ca­tionTo­ken iden­ti­fies Rasp­berry Pi from the de­vice spec­i­fi­ca­tions through the Ad­min in­ter­face.

You can iden­tify the new de­vices un­der the Ad­min UI in the De­vices sec­tion and Site view sec­tion. You can also reg­is­ter a de­vice man­u­ally here.

Lo­ca­tion up­date: This helps in geo map­ping your de­vice ini­tially or when­ever the de­vice is moved for bet­ter lo­ca­tion aware­ness in an associated site. To do this, pub­lish the fol­low­ing pay­load with the suit­able pa­ram­e­ters: { “hard­wareId”: “123-MyRpiSense-4567890”, “type”:”De­viceLo­ca­tion”,

“re­quest”: {

“lat­i­tude”: “18.5204”,

“lon­gi­tude”: “73.8567”,

“el­e­va­tion”: “560”,

“up­dateS­tate”: false,

“even­tDate”: “2017-06-01T12:00:00.390Z” } }

Send­ing mea­sure­ments: To send mea­sured val­ues from a de­vice like Rasp­berry Pi, let’s look at pub­lish­ing sys­tem met­rics like the load av­er­age of the CPU and me­mory us­age, pe­ri­od­i­cally. In Node.js and NodeRED en­vi­ron­ments, these can be cal­cu­lated with the fol­low­ing code, con­sid­er­ing avg1 and avg5 as the load av­er­age for the last 1 minute and 5 min­utes, re­spec­tively, and pmem as me­mory util­i­sa­tion. You may also add the av­er­age of the last 15 min­utes as one more prop­erty.

const os=re­quire(‘os’); var avg1 = os.loa­d­avg()[0]; var avg5 = os.loa­d­avg()[1]; var pmem=(100 - (os.freemem()/­talmem())*100).toFixed(2);

Now form the pay­load in the fol­low­ing for­mat, and pub­lish pe­ri­od­i­cally or on an event ba­sis. { “hard­wareId“: “123-MyRpiSense-4567890”, “type“: “De­viceMea­sure­ments”, “re­quest“: {

“mea­sure­ments“: {

“rpi.loa­d­avg1”: avg1, “rpi.loa­d­avg5”: avg5, “­age­mem”: pmem, },

“up­dateS­tate“: true,

“even­tDate“: now } };

If you have a suit­able tar­get board and sen­sors, you can send bet­ter pay­loads, say, weather met­rics like tem­per­a­ture, hu­mid­ity, pres­sure, etc, or mo­tion sens­ing met­rics like roll, pitch and yaw from an ac­celerom­e­ter’s or gy­ro­scope’s in­puts. The SenseHAT ad­don board for Rasp­berry Pi is a good choice for these sen­sors.

Send­ing alerts: A de­vice can send alerts when anom­alies are de­tected in mea­sured val­ues by pub­lish­ing the fol­low­ing pay­load:

{ “hard­wareId”: “123-MyRpiSense-4567890”, “type”:”De­viceAlert”,

“re­quest”: {

“type”: “rpi.cpuover­load”,

“level”: “Warn­ing”,

“mes­sage”: “CPU Loa­d­avg is very high!!”, “up­dateS­tate”: false,

“even­tDate”: now,

“meta­data”: {

“loa­d­avg”: avg,

“method”: “up­time” }

} }

De­liv­er­ing com­mands: SiteWhere can send com­mands to de­vices through its out­bound pro­ces­sors in Pro­to­buf or JSON for­mats. De­vices can re­ceive them through the MQTT Sub­scribe op­er­a­tion us­ing the topic name /SiteWhere/sys­tem/<hard­wareId> for sys­tem gen­er­ated com­mands on an event ba­sis and /SiteWhere/ com­mands/<hard­wareId> for custom com­mands. You can reg­is­ter a groovy script to trig­ger custom com­mands when anom­alies are de­tected in the de­vice mea­sure­ments as de­scribed in http://doc­u­men­ta­­to­ri­als/ rasp­berry-pi.html. You can also in­voke custom com­mands man­u­ally un­der the De­vices sec­tion. Com­mands can also be de­liv­ered via the Twilio ser­vice or CoAP library. Custom com­mands need to be added in the Ad­min UI un­der De­vice spec­i­fi­ca­tions. We can find the trig­gered com­mand by pars­ing the re­ceived pay­load.

Ac­knowl­edg­ing com­mands: The de­vice can ac­knowl­edge de­liv­ered com­mands by pub­lish­ing a suit­able pay­load, by quot­ing back the orig­i­nal event ID and de­vice re­sponse as de­scribed in doc­u­men­ta­ user­guide/send­ing-data.html. You can ob­serve all these events by brows­ing the tar­get de­vice or associated site in the ad­min in­ter­face. You can also list the events through var­i­ous REST APIs on the spec­i­fied path with the GET method and suit­able to­kens.


Most of the plat­form’s func­tion­al­ity is avail­able through var­i­ous REST APIs, apart from the Ad­min in­ter­face, and any ex­ter­nal en­tity can avail these ser­vices. For sim­ple, in­ter­ac­tive us­age of these APIs, a Swag­ger UI is added to make suit­able re­quests and check the re­sponse in JSON for­mat.

Here are some ex­am­ples of REST calls with the fol­low­ing com­mon head­ers for au­then­ti­ca­tion pur­poses.

Head­ers: {

Autho­riza­tion: Ba­sic Cre­den­tials: ad­min:pass­word

Fig­ure 1: Ar­chi­tec­ture and in­te­gra­tion of SiteWhere

Newspapers in English

Newspapers from India

© PressReader. All rights reserved.