sitewhere整体结构architecture

Global Components

As shown in the architecture diagram, SiteWhere is composed of many different components that are wired together to provide the core platform. In the sections below, we will cover the components that are global to the system. All tenants share these global settings.

Web Application Container

SiteWhere is deployed as a Web Application Archive (WAR) file and is designed to run in a web container such as Apache Tomcat. SiteWhere will run on a vanilla version of Apache Tomcat assuming the configuration files are copied into the Tomcat conf folder. The configuration files may be altered to change the way SiteWhere processes device events and integrates with external services.

SiteWhere是采用的是WAR文件，运行在网络container下，比如Tomcat。改变配置文件来更改设备处理事件，使得外部成为一个整体。

SiteWhere Server

SiteWhere Server is the central application that controls all of the other SiteWhere components. It is started automatically from the deployed WAR file and bootstraps using a Spring configuration file located in conf/sitewhere/sitewhere-server.xml. The server manages the common system components such as user management and the REST services. It also bootstraps one or more tenant engines which handle most of the other processing logic.服务器是控制其他部件的中心应用。从部署好的WAR文件自动开始，用conf/sitewhere/sitewhere-server.xml来进行boot。这个服务管理用户，REST服务，也引导出多个tenant引擎，用来处理大部分逻辑。

Administrative Application管理应用

SiteWhere includes an HTML5 administrative application that can be used to manage how the system functions. The information that appears in the application is dependent on the login credentials provided and the permissions associated with that user. By default, a new SiteWhere instance has a single admin user that has all permissions and is associated with the default tenant.包括一个HTML5的管理应用，可以用来管理系统。。。。。只有一个管理员，有最高权限。

Some aspects of the system such as users and tenants are managed globally. Changes made to these entities will be reflected across all tenants. Administrative access at this level should be limited since these users can create new users and tenants as well as shutting down running tenants, deleting existing users and affecting other system data across the board.用户和租户都是全局的。这个层次的话，需要限制下，不能影响其他

Most other aspects of the system are tenant-specific. Each user account may be associated with one or more tenants, allowing the user to manage information for multiple tenants. When logging in to the system, if a user is associated with more than one tenant, they are asked to choose which tenant to manage before proceeding. All other system data such as sites, device specifications, devices, assignments, etc are managed at a per-tenant level, so most of the data in the administrative interface depends on the user logged in and which tenant was selected.

REST Services

Most of the core functionality related to the SiteWhere APIs is accessible externally via REST services. Using the services, an external entity can create, view, update, or delete entities in the system. The services can also interact with subsystems such as asset management. All REST calls are subject to authentication and use Spring Security to verify that the user is authorized for the operation.与SiteWhere APIs相关的功能可以通过REST service来获得。利用REST 服务，可以创建，观察，升级或者删除。所有REST调用都要经过验证，并使用Spring安全性来验证用户的操作权限。

SiteWhere includes a working version of Swagger which adds a user interface around the REST services. Using the Swagger interface, you can interactively execute REST calls against a running SiteWhere server and view the JSON responses. The default Swagger URL for a server is:包括一个Swagger版本，，，利用Swagger接口，可以执行REST调用，看JSON的调用，默认的URL

http://sitewhere.hostname/sitewhere/

where sitewhere.hostname is the hostname of the server running SiteWhere.（我们这里有自己的服务器）

Global Datastore

When storing and retrieving data, SiteWhere never deals directly with a database. Instead, the system defines Service Provider Interfaces (SPIs) for the data operations it needs to operate and expects datastore implementations to comply with the required interfaces. The user management datastore is configured at the global level and is based on the following APIs:存储，获取数据，SiteWhere从不直接和数据库打交道，而是，定义SPIs服务。基于下面的APIs，可以在全局配置。

IUserManagement: Contains all of the core user management calls including CRUD methods for users, authorities, etc.

When configuring a new SiteWhere server instance, you change settings in the core Spring configuration file to indicate which type of datastore to use for the underlying data implementation. The types of datastores currently supported include MongoDB and Apache HBase.配置新的SiteWhere服务时候，在Spring配置文件中改。。

Hazelcast Services

Hazelcast is an in-memory datagrid designed with high performance in mind. By default, each SiteWhere Server instance also acts as a Hazelcast instance. In the default global configuration, the Hazelcast configuration is loaded from conf/sitewhere/hazelcast.xml. Hazelcast support can be removed by removing the corresponding entry from the configuration file.高效能，，，，

SiteWhere can use Hazelcast to interactively broadcast event data to other interested systems. For example, the SiteWhere plugin for Mule Studio uses Hazelcast to connect to a SiteWhere server instance and pull events into the bus as they occur. The events can then be processed using Mule flow logic in order to integrate event data with other cloud systems or perform other asynchronous processing tasks in real time. Access to Hazelcast clients can be limited by adjusting the SiteWhere server Hazelcast configuration so that, for instance, only machines in certain IP ranges can receive the event data.

Tenant Components

Most components of the system are configured at the per-tenant level. This allows for clean separation of data and processing logic from one tenant to the next.

Tenant Engines

SiteWhere (starting with version 1.2.0) is designed as a multitenant system. That means that multiple IoT applications can be served from a single SiteWhere instance. Each system tenant has a separate data store so data is not intermingled between tenants. Each tenant also has a separate processing pipeline that can be customized without affecting the processing of other tenants. When SiteWhere Server starts for the first time, a default tenant is created based on the default tenant configuration file found at conf/sitewhere/sitewhere-tenant.xml. The default configuration is copied to a tenant-specific configuration file located atconf/sitewhere/xxx-tenant.xml where xxx is the unique id for the tenant. Making changes to the configuration file for a tenant will alter the processing logic for just that tenant. New tenants can be added from the SiteWhere administrative application. Once created, tenants can be started and stopped dynamically without shutting down the entire server. For instance, to make configuration changes to one tenant, it may be shut down, reconfigured, and brought back up without affecting other running tenants.在1.2.0版本之后就是多用户系统。多个IoT应用可以通过一个SiteWhere来服务。每一个系统用户的数据存储分离，相互不影响。第一次运行时候，默认用户基于conf/sitewhere/sitewhere-tenant.xml文件来创建。可以通过SiteWhere管理应用来创建。一旦创建，可以单独控制start和stop，不需要对整个系统进行start和stop。

Tenant Datastores

As with global datastores, tenant datastores configure SPI implementations that provide persistence of tenant-level information such as device and asset management. Service provider interfaces implemented include:

IDeviceManagement: Contains all of the core device management calls including CRUD methods for sites, specifications, devices, events, etc.设备管理

IAssetManagement: Contains all of the core asset management calls including CRUD methods for asset categories and assets.

Tenant datastores are configured in the conf/sitewhere/xxx-tenant.xml configuration file (where xxx is the tenant id).资源管理

Communication Engine

The SiteWhere communication engine handles all functionality related to interacting with devices. Its responsibilities include:

Registration of new or existing devices

SiteWhere devices can be created manually with API calls, but it is often preferable to have devices self-register. In that case, the device provides a unique hardware id and a specification token to the system which in turns creates a new device record that can start accepting events. SiteWhere assumes that each device will have a unique id in the system so it can be independently addressed. The specification token passed at startup indicates the type of hardware the device is using and references a device specification that already exists in the system. Devices send a registration event when they boot or connect to the network and SiteWhere either creates a new device record or finds an existing one. SiteWhere returns a response message to the device indicating the registration status.每一个devices有一个特有的id。在启动时所传递的规格说明，该设备正在使用和引用系统中已经存在的设备规范。。。。。

Receipt of events from connected devices

Once registered with the system, devices can report any number or type of events to SiteWhere, which in turn stores the events. Event types include location updates, sensor measurements and other acquired data, or alerts in response to exceptional events. Devices also have the ability to acknowledge receipt of commands issued by SiteWhere. Events are delivered to SiteWhere via an inbound event pipeline which provides a modular way of introducing new functionality for processing incoming data.一旦在系统中注册，设备就可以报告数量，或者事件种类给SiteWhere，存储事件。事件种类包括事件位置，测量，或者其他的一些数据。通过inbound事件pipeline来传入事件。

Delivery of commands to connected devices

Each device registered with SiteWhere has an associated device specification which is tied to the type of hardware running on the device. Each device specification has a list of commands that can be executed against devices with that specification. SiteWhere allows any number of commands to be added for a specification and each command can carry any number of arguments. The commands and arguments can be added via the administrative user interface or via REST calls. When commands are executed, they travel through a pipeline that encodes them in an expected format and delivers them across an expected protocol.

The flow of data in the SiteWhere communication engine is shown below:

Asset Modules

SiteWhere assets represent objects in the physical world -- people, places, and things. Device specification assets are used to describe the hardware information/configuration for a type of device. Device assignment assets are used to describe an entity associated with a device -- a person associated with a badge or a bulldozer associated with a location tracker or a hospital ward associated with a piece of hospital equipment.里面的assets代表了现实世界中的人，物等。特殊设备assets被用来描述硬件信息，配置。

Rather than hard-coding a schema for assets in the system, SiteWhere defines SPIs for general asset types and allows asset modules to be plugged in to provide asset definitions. This allows existing identity management systems to be used in providing a list of available person assets. It also allows product catalog systems to be used in defining available hardware assets. SiteWhere uses asset modules in a read-only manner and only ever references entities based on a unique id understood by the underlying asset module. Maintaining the list of available assets is left to the systems behind the asset modules (which usually already have a user interface specific to the features they provide).不是硬件编码，SiteWhere为assets的种类定义SPIs，提供assets定义。

SiteWhere also provides the concept of asset categories, which reside in the SiteWhere datastore. Asset categories are containers for assets of a given type and may be added/edited from within the administrative console. Asset categories are loaded as asset modules at runtime, allowing assets to be pulled from the datastore in addition to modules loaded from other sources such as XML files or third-party systems.

Object Model

SiteWhere provides a comprehensive object model that captures the relationships between all of the various concepts in tracking device data. The diagram below shows some of the core objects in the model and their relationships:

Sites

Sites are used to organize devices that are related so that their events can be looked at from a grouped perspective. The primary use case for sites is in location-aware devices. A site provides a containing entity to which a map can be assigned so that location data can be viewed in the context of that map. When creating a site in the administrative application, you can assign a map type and initial location/zoom so that location events for that site are rendered on the given map. The map rendering code uses the Leaftlet JavaScript map library and is able to create a dynamic overlay layer based directly on SiteWhere REST calls. Currently supported map types include:

Mapquest World Map

Used to render location data on a world map using MapQuest tiles.

GeoServer Custom Map (Custom Tileset)

Used to render data on a custom GeoServer tile layer. This allows unique maps and floor plans to be used as the background for SiteWhere location rendering. The maps can include custom vector or raster data specific to the location data being visualized.

More map types will be added in the near future, but most use cases are covered by the existing map types.

SiteWhere was originally written as a system to track location-aware devices. Sites provided a way to group devices in the same physical vicinity (for instance in the same office building). There are some use cases that do not necessarily require the location-based aspects of sites, but they can still benefit from being able to view events across a group of related devices.

Zones

Another important feature for location-aware applications is the concept of zones that carry special meanings. For instance, in an airport, there are secure areas where only certain personnel should be allowed. In an application that monitors airport security, it makes sense to be able to fire an alert if an unauthorized person enters a secure zone.

The SiteWhere administrative application allows zones to be defined based on the map associated with a site. In the zone editor, you can click points on the map to set the boundaries of the zone. You can also specify the border and background colors as well as the opacity of the overlay when shown on the map. The Leaflet overlays automatically load the list of zones for a site when displaying its map. On the integration side of things, SiteWhere provides a node in Mule Studio that will compare locations coming into the system against defined zones, allowing the developer to react to devices entering or exiting zones.

Device Specifications

Specifications are used to capture characteristics of a given hardware configuration. This is not necessarily a one-to-one mapping to a part number or SKU since some peripheral devices may have been added or certain characteristics upgraded. A device specification contains a reference to a hardware asset which provides the basic information about the hardware including name, description, image URL, etc.

Device Specification Commands

A device specification contains a list of commands that may be invoked by SiteWhere on the device. Commands can be added, updated, viewed, and deleted in the admin UI or via the REST services. It is perfectly acceptable for two device specifications to point to the same asset type, but have a different set of commands, reflecting different configurations of the given device.

Device Command Invocations

SiteWhere provides APIs for invoking commands on a device based on the list available in its device specification. Each command invocation is captured as an event associated with the current device assignment. The admin UI and REST services allow commands to be invoked and previous invocations for an assignment to be searched.

Device Command Responses

After a device processes a command invocation, it may return a response to SiteWhere. Command invocation messages carry an originator event id that can be sent back with any responses to tie responses back to the event that they are responding to. SiteWhere provides a simple ack event that acknowledges receipt of an event. Devices can also return locations, measurements, or alerts in responses to commands and use the originator id to associate those with a command as well. From an API perspective, a user can list the responses for a given command (any number of responses can be associated) and act on the responses to initiate other actions.

Devices

Devices are a SiteWhere representation of connected physical hardware that conforms to an assigned device specification. Each device is addressable by a unique hardware id that identifies it uniquely in the system. A new device can register itself in the system by providing a hardware id and device specification token. SiteWhere in turn creates a new device record via the APIs and (optionally) creates a placeholder unassociated device assignment (see below) to allow events to be collected for the device. Devices can be manually added via the REST services or via the admin UI.

Device Groups

Device groups allow multiple related devices or subgroups to be organized into logical units. The groups can then be used for performing operations collectively rather than performing them on a per-device basis. Each group can have zero or more roles assigned to it, allowing arbitrary groupings based on application needs. Devices may belong to multiple groups and may be assigned zero or more roles within the group. This structure allows queries such as "find all devices from the 'heavy-equipment' group that have the role 'leased-equipment' and issue a 'getCurrentLocation' command".

Device Assignments

Events are not logged directly against devices, since a given device may serve in a number of contexts. For instance, a visitor badge may be assigned to a new person every day. Rather than intermingle event data from all the people a badge has been assigned to, the concept of a device assignment allows events to be associated with the asset they relate to. A device assignment is an association between a device, a site, and (optionally) a related asset. Some assignments do not specify an asset and are referred to as unassociated. A real-world example of this is a vending machine that has wireless connectivity to report inventory. The device isthe asset, so there is no need to associate an external asset.

Current Device State

Device assignments also act as a storage bin for recent device state. As events are processed for an assignment it can keep a record of the most recent event values. By default, the assignment stores the most recent location measurement, the most recent value for each measurement identifier, and the most recent alert for each alert type. Using this stored state, SiteWhere can infer the current state of a device without having to send a command to request new data. Included in the state information is the date on which the data was stored, so logic can intelligently choose when to request an update of the data.

Assignment Status Indicator

Each device assignment also holds a status of the assignment itself. By default, an assignment is marked active immediately after it is created. Using the REST services or admin UI, the status can be changed to missing if the device or associated asset have been reported missing. Processing logic can be altered for missing assignments. The assignment status is updated to released when an assignment is terminiated. This indicates the device is no longer assigned and may be reassigned.

Device Events

Device events are the data generated by connected devices interacting with SiteWhere. They are the core data that SiteWhere revolves around. SiteWhere captures many types of events including:

Meaurements

Measurement events send measured values from a device to SiteWhere. Measurements are name/value pairs that capture information gathered by the device. For instance, a weather sensing device might send measurements for temperature, humidity, and barometric pressure. A single measurements event can send any number of measurements to SiteWhere (to prevent the overhead of having to repeatedly send multiple events to capture state).

Locations

Location events are used to reflect geographic location (latitude, longitude, and elevation) for devices that have the ability to measure it. Location events are stored with a geospatial index when added to Solr so that they may be queried as such.

Alerts

Alert events are sent from a device to indicate exceptional conditions that SiteWhere may need to act on. For instance, a fire alarm might send a smoke detected alert to indicate it has been triggered. Alerts contain two primary pieces of information: a type and a message. The alert type is used to identify which class of alert is being fired. The alert message is a human-readable message suitable for displaying in a monitoring application.

Command Invocations

Each time a command is invoked via SiteWhere, the information about the invocation is stored as an event for the current device assignment. The invocation captures which command was executed, when it was executed, values for command parameters, etc.

Command Responses

If a device generates a response to a command invocation, the response is stored as an event. Responses may be in the form of measurements, locations, alerts, or acks. If the device passes an originating event id with the response, the response is tied back to the original command invocation. The REST APIs allow all responses for a given command invocation to be enumerated so that they can be processed.

All event types share some common information that applies more generally to events. Each event records an event date and a received date. The event date is the timestamp for when the data was gathered by the device. It is important to understand that some devices cache events to prevent the battery drain of network access. Because of this, the event date may differ significantly from the received date, which is the date that the event was processed by SiteWhere. All events also contain an area for arbitrary metadata. This allows application-specific information to be piggy-backed on events so it can be used in later processing.