SiteWhere物联网云平台架构

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

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 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 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 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 is the 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.