With the
release of SiteWhere 2.0, the SiteWhere 1.x platform will no
longer be actively maintained. The SiteWhere team will continue to
provide bug fixes for the 1.x platform through the end of 2019,
but no new features are planned. To start using SiteWhere 2.0,
access the new website at the URL below:

System Overview

This guide is intended to provide a high-level understanding of what SiteWhere does and how it
is implemented.

What is SiteWhere?

SiteWhere is an open source IoT platform. It provides a system that facilitates the ingestion,
storage, processing, and integration of device data. SiteWhere provides the following
functionality:

IoT Server Platform

Supplies a server based on proven technologies that acts as a controller for the processing of
device data. The server can be installed on a local machine or run in the cloud and is built on
technologies that are designed to scale to billions of processed device events per day.

Provides long-term persistence of data sent from devices. Historical device event data is valuable
and SiteWhere offers a platform where data is never deleted, no matter the volume of events.

Offers service provider interfaces (SPIs) that provide a core object model for the platform and
allow third parties to extend and customize the system to work with new technologies.

Delivers an advanced device communication system that allows control of the full lifecycle of
registering devices, sending commands based on hardware type, receiving data responses and
aggregating them. The system is based on a core set of interfaces that allow new communication
protocols and encoding schemes to be added and configured easily.

Provides an HTML5 administrative application that allows all of the system data to be viewed and manipulated
in a way that makes it easy to understand the data. The admin app uses REST services provided by
the core platform to interact with the data. Third party applications can use the same REST services
to interact with SiteWhere data without having to use the admin application.

Device Management

Provides a complete device management model. Device specifications allow classes of devices to be
declared along with metadata that provides extended context for devices. Devices are created based
on specifications along with unique information such as a hardware id and device-specific metdata.
Device assignments allow devices to be associated with physical assets. Device groups allow many
devices to be targeted based on group relationships and metadata.

Provides a model for standard types of data generated by devices. Events such as value measurements,
alert conditions, and location updates are stored in massively scalable time series datastores.
Device command invocations and responses are tracked and correlated along with state events such
as device registrations and presence detection. All events are linked to based on the currently
assigned asset for fine-grained tracking.

Associates devices with external assets such as people or physical items. For instance, a badge may
be associated with the person wearing it. A tracking device can be associated with the piece of heavy
equipment it is attached to. The asset information is offered via an asset management framework that
allows external systems to drive the information. For instance, the list of people that badges can be assigned
to can come from an existing LDAP data store. SiteWhere tracks the assignment of devices to assets over time
and ties events to the assignment so at a later date you can query what were the locations of the badge
when it was assigned to this person.

Integration

Integrates with third party integration frameworks such as Mule AnyPoint,
allowing event data to trigger complex interactions such as adding data to Salesforce or notifying
alert conditions using text messages generated by Twilio.

Offers a Java client that can interact with most of the provided REST services. For external systems
with existing Java code, interfacing with SiteWhere is as simple as a few lines of code.

Protects information by limiting access to data based on a proven user management system. The system
can be configured to use external sources of identity data such as LDAP data stores.

Core Platform Technologies

Rather than reinventing the wheel, SiteWhere depends on many supporting open source technologies to
accomplish its goals. Most of the technologies used have been tested for years in production environments
and have been continuously upgraded thanks to many iterations of improvements. The following open
source components are used by SiteWhere:

Apache Tomcat 7

Tomcat provides the core server in which SiteWhere runs. SiteWhere is
deployed as a web archive (WAR file) that runs when the Tomcat server is started.

Spring Framework

Spring delivers the core configuration framework that bootstraps SiteWhere and
allows it to be configured and extended. Rather than using a hard-coded set of components, SiteWhere has
a core set of service provider interfaces and default implementations of the interfaces. By using the same
interfaces in custom classes and plugging them in via Spring, a third parties can extend SiteWhere without
touching the core code.

Spring Security

Spring Security provides the core security infrastructure
for SiteWhere. SiteWhere has its own user management interfaces, but also implements interfaces from
Spring Security, allowing it to use existing security components for authenticating access to system
resources. For instance, Spring Security annotations are used to control who can access the REST services.

Hazelcast

Hazelcast is an in-memory data grid that allows for high performance data processing
across a cluster of servers. SiteWhere uses Hazelcast to provide subscription-based access to events being
processed. An external entity can use the Hazelcast client to connect to a running SiteWhere instance and
listen to a feed of events including location data, measurements, alerts, and command invocations.

Data Storage Technologies

SiteWhere supports storing data in many of the most scalable persistence stores available. The storage
implementations are plugged in via service provider interfaces so SiteWhere interacts with them in
a consistent fashion. This allows new storage technologies to be added easily.

MongoDB

MongoDB is a NoSQL database that can be used to store SiteWhere data. It is
very quick and easy to install, has great performance, and does not require the computing resources of HBase.

Apache HBase

HBase is a distributed, non-relational data store that allows relatively unlimited
data storage with near linear scalability as new hardware is added to the cluster. SiteWhere uses a customized
HBase schema to store device events as time series data
that is optimally distributed across a cluster, allowing fast access to events based on the time they were gathered.

InfluxDB

InfluxDB is a highly-scalable time series database that supports advanced
clustering. SiteWhere can use a hybrid approach where device management data is stored in MongoDB while
event data is stored in InfluxDB. With this approach, tools such as Grafana can be
used to visualize SiteWhere data.

Integration Technologies

In addition to the technologies used to implement core SiteWhere features, there are a number of
complementary technologies that enhance SiteWhere. These include:

Mule AnyPoint Platform

Mule AnyPoint is an integration platform that provides access to almost any
communication protocol or cloud technology you can imagine. For instance, using Mule you could read messages
from a folder on the file system, parse them, then deliver them to SiteWhere via REST services. On the other
side of the coin, you could have Mule respond to events after the fact. For example, if an alert event of a
given type and severity is detected, Mule can interface with Twilio and send out an SMS message to alert the
responsible party to respond. Mule AnyPoint Studio is a powerful IDE
that allows mule flows to be designed graphically. SiteWhere has a plugin for Mule Studio that allows flows to
subscribe to device events using a drag-and-drop visual approach.

Asset Management Systems

SiteWhere supports the use of asset management systems in associating devices with external entities such
as people, locations, or hardware. Assets can be stored internally using the built-in SiteWhere asset
management features. Assets can also be loaded from external systems so that existing information can be
leveraged.

WSO2 Identity Server

WSO2 Identity Server is an identity management solution that
allows user information to be accessed from a number of different storage providers using the SCIM protocol.
This allows SiteWhere's asset management framework to use a single API to access user information stored in
databases, LDAP stores, or any other supported format. The person assets may then be assigned to devices so
that SiteWhere has more context in reacting to events. For instance, if an alert condition occurs, SiteWhere
can originate an automated call to the cell phone registered to the user assigned to a device.

Potential Use Cases

The possible uses for SiteWhere are endless. Almost any industry can benefit from some level of monitoring, automation,
and analytics. Below are a few examples of real-world uses for SiteWhere:

Vehicle Tracking

Whether monitoring a rental car fleet or a few very expensive pieces of heavy equipment, it makes sense to track
the location of vehicles and monitor their condition over time. An automated system based on SiteWhere could help
in theft prevention, monitor service intervals or point out trends in maintenance costs based on vehicle type.

Home Automation

Home automation is one of the fastest growing areas in IoT. Many devices that were once passive now
contain microcontrollers and have the ability to be monitored or actuated externally. SiteWhere provides a
central system for extended retention of measurements from devices and facilitates sending commands in response
to various conditions. Many off-the-shelf systems are customizable, but SiteWhere is truly programmable. An
example of the power of SiteWhere in the cloud is a climate control system. A system could be designed to learn
wake/sleep patterns and temperature preferences. Since SiteWhere can operate in the cloud, your climate profile
could follow you when you check into a hotel, so that the room is already confortable when you check in and
adjusts itself on your schedule.

Medical

The medical industry is full of opportunities for monitoring, automation, and analytics. For instance, monitors
attached to patients could gather a patient's vital signs on a short interval, storing them in SiteWhere. Doctors
could use the stored data to look for signs of abnormal readings. Better yet, SiteWhere analytics could automatically
analyze the data and look for outlying data, even cross-referencing data between patients to draw more global
conclusions. Data from local hospital SiteWhere instances could be aggregated with data from other hospitals to
create larger study groups, revealing otherwise hidden trends.