SystemArchitecture系统架构

Thisdocument describes the components that make up SiteWhere and how theyrelate to each other.

这个文档描写叙述了sitewhere组件和组件之间的关系。

ArchitectureDiagram架构图

Thefollowing diagram shows the main SiteWhere server components and howthey interact with externalsystems.下图展示了sitewhere服务器组件以及组件怎样与外部系统的交互。

GlobalComponents全局组件

Asshown in the architecture diagram, SiteWhere is composed of manydifferent components that are wired together to provide the coreplatform. In the sections below, we will cover the components thatare global to the system. All tenants share these global settings.

如上面架构图所看到的，SiteWhere是由很多不同的组件组成，它们彼此连接共同组成核心平台。

以下我们将介绍这些全局性的系统组件。全部的租户共享这些全局配置。

WebApplication Container Web应用容器

SiteWhereis deployed as a Web Application Archive (WAR) file and is designedto run in a web container such as Apache Tomcat. SiteWhere will runon a vanilla version of Apache Tomcat assuming the configurationfiles are copied into the Tomcatconffolder. The configuration files may be altered to change the waySiteWhere processes device events and integrates with externalservices.

Web应用容器

SiteWhere採用WAR文件部署，设计在web容器中运行，如apachetomcat。Sitewhere将在apachetomcat vanilla版本号上运行，tomcat採用的配置文件直接复制到tomcatconf目录。

配置文件做了一些更改，用来处理设备事件，与外部服务集成。

SiteWhereServer SiteWhere服务器

SiteWhereServer is the central application that controls all of the otherSiteWhere components. It is started automatically from the deployedWAR file and bootstraps using a Spring configuration file located inconf/sitewhere/sitewhere-server.xml. The servermanages the common system components such as user management and theREST services. It also bootstraps one or moretenant engineswhich handle most of the other processing logic.

SiteWhere服务器是核心应用。用来控制全部相关的组件。

SiteWhere服务器从WAR文件部署就自己主动开启，採用spring配置文件conf/sitewhere/sitewhere-server.xml进行初始化。服务器管理经常使用的组件，如用户管理。REST服务。也会启动一个或多个租户引擎用来处理其它的业务逻辑。

AdministrativeApplication后台管理应用

SiteWhereincludes an HTML5 administrative application that can be used tomanage how the system functions. The information that appears in theapplication is dependent on the login credentials provided and thepermissions associated with that user. By default, a new SiteWhereinstance has a singleadmin user that has allpermissions and is associated with the default tenant.

SiteWhere包含了HTML5后台管理应用，能够用来管理系统怎样工作的。后台管理的信息依赖于提供给用户的登陆凭证以及用户相关的权限。普通情况下，一个新的sitewhere实例就有一个单独的admin用户拥有全部权限，并关联一个缺省租户。

Someaspects 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 theseusers can create new users and tenants as well as shutting downrunning tenants, deleting existing users and affecting other systemdata across the board.

像用户、租户一些都是全局管理。这些实体的改变会反映在全部租户中。后台管理的訪问要被限制。由于这些用户能够创建新用户、租户。也能关闭运行的租户，删除现有的用户，影响其它的系统数据。

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

系统大部分特性都是租户相关的。每一个用户帐号能够与一个或多个租户关联。同意用户管理多个租户的信息。当用户登陆到系统中时。假设与一个以上的租户关联，他将在处理前被要求选择哪个租户来管理。全部其它的系统数据，如网站，设备规格，设备，关联等等，都是在每一个租户层面上管理的，因此大部分后台管理界面的数据依赖于登陆的用户和选择的租户。

RESTServices

Mostof the core functionality related to the SiteWhere APIs is accessibleexternally via REST services. Using the services, an external entitycan create, view, update, or delete entities in the system. Theservices can also interact with subsystems such as asset management.All REST calls are subject to authentication and use Spring Securityto verify that the user is authorized for the operation.

REST服务

sitewhereAPIs相关的大部分核心功能都能够通过REST服务訪问。通过REST服务，外部实体能够在系统中创建、查看、更新、删除系统中的实体。

服务也能够与诸如资产管理的子系统交互。全部的REST调用都须要认证，系统採用了spring安全机制确保用户操作的授权。

SiteWhereincludes a working version ofSwaggerwhich adds a user interface around the REST services. Using theSwagger interface, you can interactively execute REST calls against arunning SiteWhere server and view the JSON responses. The defaultSwagger URL for a server is:

http://sitewhere.hostname/sitewhere/

wheresitewhere.hostname is the hostname of the serverrunning SiteWhere.

sitewhere包含了一个swagger的工作版本号，为REST服务添加用户界面。使用swagger界面，你能够运行REST调用，而不是查看sitewhere服务器，浏览JSOAN响应。

缺省的swaggerURL为：

http://sitewhere.hostname/sitewhere/

sitewhere.hostname是运行sitewhere的服务器。

GlobalDatastore

Whenstoring and retrieving data, SiteWhere never deals directly with adatabase. Instead, the system defines Service Provider Interfaces(SPIs) for the data operations it needs to operate and expectsdatastore implementations to comply with the required interfaces. Theuser management datastore is configured at the global level and isbased on the following APIs:

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

全局数据存储

当存储和获取数据时。sitewhere不会直接处理数据库。系统为数据操作定义了服务提供接口（SPIs）。用来操作数据。用户管理的数据存储在全局配置，基于以下的APIs

IUserManagement：包含了全部核心用户管理调用。用户权限的CRUD操作。

Whenconfiguring a new SiteWhere server instance, you change settings inthe core Spring configuration file to indicate which type ofdatastore to use for the underlying data implementation. The * ofdatastores currently supported include MongoDB and Apache Hbase.

当配置新的sitewhere服务器实例时，你要改动核心的spring配置文件指出数据存储的类型。眼下数据存储的类型支持Mongodb和apacheHbase。

HazelcastServices

Hazelcastis an in-memory datagrid designed with high performance in mind. Bydefault, each SiteWhere Server instance also acts as a Hazelcastinstance. In the default global configuration, the Hazelcastconfiguration is loaded from conf/sitewhere/hazelcast.xml.Hazelcast support can be removed by removing the corresponding entryfrom the configuration file.

Hazelcast服务

hazelcast是一个分布式内存网络平台。高性能。通常，每一个sitewhere服务器实例也是Hazelcast实例。

全局配置下。hazelcast配置文件位于conf/sitewhere/hazelcast.xml。Hazelcast支持能够被去除。

SiteWherecan use Hazelcast to interactively broadcast event data to otherinterested systems. For example, the SiteWhere plugin for Mule Studiouses Hazelcast to connect to a SiteWhere server instance and pullevents into the bus as they occur. The events can then be processedusing Mule flow logic in order to integrate event data with othercloud systems or perform other asynchronous processing tasks in realtime. Access to Hazelcast clients can be limited by adjusting theSiteWhere server Hazelcast configuration so that, for instance, onlymachines in certain IP ranges can receive the event data.

sitewhere能够使用hazelcast为其它关联的系统广播事件数据。比如。sitewhere插件mulestudio採用hazelcast连接sitewhere服务器实例。把时间推送至公车。

这些事件能够採用muleflow逻辑处理。与外部云系统集成数据，或者运行同步任务。

Hazelcast客户端訪问权限能够通过调整sitewhere服务器hazelcast的配置文件来限制。比如，仅仅有某个IP地址范围的机器能够接受事件数据。

TenantComponents

Mostcomponents of the system are configured at the per-tenant level. Thisallows for clean separation of data and processing logic from onetenant to the next.

租户组件

系统大部分组件都是在每一个租户层面上配置，这就实现了租户之间的数据和处理逻辑隔离。

TenantEngines

SiteWhere(starting with version 1.2.0) is designed as a multitenant systemwhich means that multiple IoT applications can be served from asingle SiteWhere instance. Each system tenant has a separate datastore so data is not intermingled between tenants. Each tenant alsohas a separate processing pipeline that can be customized withoutaffecting the processing of other tenants. When SiteWhere Serverstarts for the first time, a default tenant is created based on thedefault tenant folder found at conf/sitewhere/tenant-template.

租户引擎

sitewhere（1.2.0版本号以后）就被设计成了多租户系统，意味着多个IOT应用能够被一个sitewhere实例服务。

每一个系统租户都有一个独立的数据存储，因此数据在租户之间不会混淆。每一个租户都有独立的处理管道。在不影响其它租户的情况下定制。

当sitewhere服务器次開始时，缺省租户依据缺省的租户文件conf/sitewhere/tenant-template被创建。

Thedefault folder structure including configuration is copied to atenant-specific configuration folder located atconf/sitewhere/tenants/xxx wherexxxis the unique id for the tenant. The tenant configuration file isnamedsitewhere-tenant.xml and is located in theroot of the folder. Making changes to the configuration file for atenant will alter the processing logic for just that tenant. Newtenants can be added from the SiteWhere administrative application.Once created, tenants can be started and stopped dynamically withoutshutting down the entire server. For instance, to make configurationchanges to one tenant, it may be shut down, reconfigured, and broughtback up without affecting other running tenants.

包含配置的缺省目录复制到租户的配置目录中conf/sitewhere/tenants/xxx，xxx是租户独一无二的ID浩。租户配置文件sitewhere-tenant.xml位于目录顶部。对于一个租户的配置改变将会改变那个租户的处理逻辑。新的租户能够通过管理应用加入。一旦创建，租户能够动态的開始和停止不须要关闭整个服务器。比如。改变一个租户的配置。可能关闭，又一次配置，回滚而不会影响到其它运行的租户。

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).

租户数据存储

作为全局数据存储，租户数据存储配置了SPI接口实现用来提供租户级别信息的持久保存，比如设备、资产管理信息。

SPI服务提供接口实现包含：

IDeviceManagement: 包含了全部核心设备管理调用。包含网站、规格、设备、事件等CRUD增删改查方法操作。

IAssetManagement: 包含了全部核心资产管理调用，包含资产分类和资产的CRUD增删改查方法操作。

租户数据存储配置在 conf/sitewhere/xxx-tenant.xml 文件里。

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.

通信引擎

SiteWhere通信引擎处理全部与设备交互相关的功能，主要作用包含：

新的设备或者已有设备的注冊

SiteWhere设备能够通过API调用手工创建，可是很多其它情况下设备自己注冊。

在这样的情况下。设备提供了独一无二的硬件id和规格token，系统依次创建新的设备记录。開始接收事件。

SiteWhere假定在系统中每一个设备都有一个独一无二的id。因此能够被独立寻址。在開始启动时传递的设备规格token指明了设备使用的硬件类型，系统中已经存在的设备规格。

当设备启动并连接到网络时，设备传送一个注冊事件，SiteWhere也会创建一个新设备记录或者找到已有的设备。SiteWhere返回一个相应消息给设备指明注冊状态。

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 * 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.

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.

从已连接设备接收事件

设备一旦在系统中注冊，就能够向SiteWhere报告不论什么事件的类型和数字，并依次保存在事件中。

事件类型包含位置更新。传感器測量值和其它获得的数据，或者异常事件的告警。设备能够接收SiteWhere发起的命令。

事件通过入站事件管道传递给SiteWhere，入站事件管道提供了一种模块化的方法来添加新的功能，用来处理传入的数据。

公布命令到已连接的设备

每一个在SiteWhere中注冊的设备都有一个关联的设备规格，设备规格指明了设备中运行的硬件类型。

每一个设备规格都有一个命令列表。能够在关联该规格的设备中运行，SiteWhere同意在设备规格中加入指令。每一个指令能够有很多參数。

这样的指令和參数能够通过后台管理界面加入，或者通过REST调用。当指令运行时，他们通过管道，採用一定的编码格式，通过一定的协议传递。

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

SiteWhere通信引擎中的数据流例如以下图所看到的：

---------------------------------------------------------------------------------------------------------------------------------------------
以下待翻译
---------------------------------------------------------------------------------------------------------------------------------------------

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.

Rather than hard-coding a schema for assets in the system, SiteWhere defines SPIs for general asset * 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 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.

资产模块

SiteWhere资产模块是指物理世界中的对象，人、地点和物体。设备规格资产是用来描写叙述一种设备的硬件信息或配置，设备关联资产是用来描写叙述与设备关联的实体。如与徽章关联的人、与位置跟踪器关联的挖掘机、与某件医院设备相关联的医院病房。

SiteWhere不是在系统中为资产硬编码一个模式。而是为通用资产类型定义了SPIs接口，同意资产模块插入并提供资产定义。

这就同意现有的认证管理系统用来提供人员资产的列表，也同意设备分类系统用来定义能够提供的硬件资产。

SiteWhere已仅仅读方式使用资产模块。仅仅依据的能够被底层资产模块理解的ID进行实体引用。

现有资产的维护就交给系统来完毕（通常实用户界面描写叙述资产的特征）。

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:

对象模型

SiteWhere提供了广泛的对象模型用来理解设备数据跟踪的各种概念之间的关系。下图展现了模型和它们之间关系的核心对象。

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 * include:

Mapquest World Map

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

网站

网站用来组织相关联的设备，从而数据能够从分组的视角查看。网站的基本用途是位置感知的设备，网站提供了与地图关联的容器实体。因此位置数据能够在地图上展示。在后台管理应用中创建一个网站时，你能够指定地图类型和初始位置，网站的位置事件在给定的地图中展现。地图渲染代码使用Leaftlet JavaScript地图库，能够直接基于SiteWhere REST调用创建一个动态的图层。

眼下支持的地图类型包含：

Mapquest World Map

採用Mapquest图块在世界地图上渲染位置数据。

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 * will be added in the near future, but most use cases are covered by the existing map *.

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.

GeoServer Custom Map (Custom Tileset)

GeoServer 定制化地图（定制图块）

用来在定制化的GeoServer图层上渲染数据。同意使用独一无二的地图和地理规划作为SiteWhere位置渲染的背景。这样的地图能够包含定制化的矢量数据或者栅格数据，用于位置数据显示。

相关文章