SiteWhere is distributed with an HTML5 administrative application that provides aneasy way to create and maintain SiteWhere data without having to do everything via the REST services. The administrative application (often referred to as the admin console or admin ui) isavailable as part of any standalone or cloud install of SiteWhere. In a default local installationthe admin console is accessible via:
SiteWhere使用HTML5開發的管理後台，創建、管理Sitewhere數據更加容易，不用通過REST服務接口。管理後台作為單機或者雲部署安裝的一部分。缺省情況下，本地安裝後，可以通過以下地址訪問管理控制台：
http://localhost:8080/sitewhere/admin/
Assuming SiteWhere is running at the given URL, the admin console login page will promptfor credentials to log in.
登陸
打開管理後台的URL，控制台登陸要求使用用戶名、密碼登陸。
In pre-1.0 versions of SiteWhere, user credentials are automatically filled in basedon the default data populated at system startup. The default username and password are
username: admin, password: password
The login credentials authenticate against the SiteWhere user model, which is populatedwith a single default user account upon the first system startup. User accounts can beadded or updated by clicking on the Users tab at the top of the admin console application.
The first page displayed after logging in to the SiteWhere administrative application is the server information page. It includes runtime information about the runningSiteWhere instance including product version and Java virtual machine state. The dynamicgraphs at the bottom of the page reflect JVM memory usage over time.
Sites are top-level entities that represent physical areas in which devices are deployed. Depending on the system being modeled, sites mayrepresent very different things. For instance, a healthcare system may have a site foreach hospital in the system. A system for monitoring heavy equipment at a number of construction sites in a city may have a site for each. A system monitoring airportpersonnel may have a separate site for each airport.
Clicking on the Sites tab at the top of the application opens the site list page. The page has an entry for each site in the system:
Each entry has icons on the right side that allow the given site to be edited, deleted,or opened.
To create a new site, click on the Add New Site button at the top of the site listpage. To change an existing site, click the edit icon at the right side of the site entry.The following sections cover information needed to create or edit a site.
The Site Details tab includes basic information about a site.
Not all sites involve location data, so the map information is optional. For sites that do need to display geospatial data, the map association allows a given map, latitude, longitude, and zoom level to be associated with a site. When viewing location data for a site, the map specified forthe site is the default used for visualizations.
Rather than manually typing the latitude, longitude, and zoom level fora map, the information may be specified interactively by clickingChoose location and zoom on map. This option presents a map whichcan be manipulated via drag-and-drop to choose the default map settings.
As with most SiteWhere data, each site may have arbitrary metadata associatedwith it. This allows sites to be tailored for application-specific functionality.For instance, if a system requires an indicator for whether a given sitehas wifi access or needs to store the phone number for contacting the site, thisinformation can be associated as metadata. The metadata can be used in deviceevent processing to take different actions based on site-specific settings.For instance, if a site offers wifi access, devices can automatically be configured to use the access point.
From the site list page, clicking on the green arrow to the right of an entry opensthe site detail page. This page shows the basic site information as well as a listof all devices assigned to the site and all associated event information.
The Assignments tab contains a list of devices assigned to the site ordered withthe most recent assignments first. Clicking on any of the assignments will openthe assignment details page for the assignment.
The Locations tab contains a list of the most recent location measurements for devices assigned to the site.
The Measurements tab contains a list of the most recent measurement values for devices assigned to the site.
The Alerts tab contains a list of the most recent alerts for devices assigned to the site.
The Zones tab contains a list of the zones defined for the site. Zones definegeospatial areas that are of interest for a site. For more information on zones, see the next section.
Zones define geospatial areas that are of interest for a site. For instance, anairport may have secure zones that define areas where only authorized agents areallowed to enter. A site may have any number of zones and the zones may overlap.A zone is defined by a list of lat/long pairs that define a polygon. Zones maybe large and complex, so there is no limit to the number of points that make upthe boundary. In addition to the boundaries, a border color, fill color, and fillopacity are defined for each zone. This allows the appearance of zones to be tailored and presented on map views.
To create a new zone, click on the Zones tab on the site details page and clickthe Add New Zone button. The zone create dialog will appear as shown below:
Enter a name for the zone into the text field at the bottom of the dialog and choosethe zone border color, fill color, and fill opacity. To add a polygon, click on the polygon tool in the upper right corner, then start clicking locations on the map toadd points. Click the first point added to complete the polygon. You can also createa rectangle by clicking on the rectangle tool and dragging to size the area. ClickCreate when you are satisfied and the zone will be created.
To change an existing zone, click the edit icon at the right side of the zone entryand make the desired changes. Existing zone borders may be altered by clicking on the existing points and dragging them to new locations. New border points may be added by clicking between existing points to add a new point, then dragging it tothe desired location.
Device specifications represent unique hardware configurations which may be assigned todevices. Two separate device specifications may use the same base platform, yet have enoughdifferences in hardware or software configuration to consider them separate when definingdevices. For instance, you might deploy a microcontroller with two configurations, one witha standard LED and another with an RGB LED.
Device specifications also cover the list of commands that may be sent to a device. In the case of the LED example above, both specifications might have a commandenableLight() to turn the LED on, but the specification with the RGB LED might alsohave a setColor() command to choose the color.
While most devices are standalone, self contained units, SiteWhere device specifications alsoaccount for more complex scenarios called composite devices. Composite devices handle the casewhere gateway devices act as a go-between for nested devices. Specifications for composite devicesprovide a schema that clearly defines where nested devices ‘plug in’ to the parent device.
Click on Specifications in the Devices dropdown in the navigation bar to open the device specificationslist page. All existing device specifications are listed in alphabetical order as shown below:
Each entry has icons on the right side that allow the given specification to be edited, deleted,or opened.
To create a new specification, click on the Add New Specification button at the top of the listpage. To change an existing specification, click the edit icon at the right side of the entry.The following sections cover information needed to create or edit a specification.
The Specification Details tab includes basic information about a device specification.
A device specification can have arbitrary metadata assigned with it so that the datacan be used later when processing events. For instance, different logic can be appliedduring event processing based on metadata such as memory configuration or cpu speedof the device in question. Metadata can be added as name-value pairs in the dialogas shown below:
From the specification list page, clicking on the green arrow to the right of an entry opensthe specification detail page. As shown below, the specification detail page contains the base specification information at the top and a set of tabs below it for modifying otherkey features.
Each device specification contains a list of commands that may be sent to a device that uses it.Each command has a unique name and a list of typed parameters that may be passed to it. The parameter types are based on the ones used for Google Protocol buffers, but it is up to theencoder on the command destination to choose how the data is transmitted across the wire.
A new command may be added by clicking the Add New Command button. The Create Device Commanddialog opens to the Command tab.
The Parameters tab allows the list of parameters to be edited. To add a new parameter,enter a parameter name, choose a type, and check the checkbox if the parameter is required.Click Add to add the parameter to the list. Existing parameters may be removed byclicking the x to the right of the entry.
Like most other SiteWhere entities, commands may have metadata associated. One use for command metadata is to provide hints to the command encoder to handle special casesaround transmission of command data.
Rather than forcing the developer to create a custom encoding scheme for sending commands,SiteWhere provides the option of generating a Google Protocol Buffers definition basedon the list of commands for a specification. Clicking on the Code Generation tab showsthe Google Protocol Buffer definition for the current list of commands. Clicking on the Refreshbutton generates a new definition if commands have been changed. Clicking the Download buttondownloads the definition to the local file system. The definition may be used to generate code inany of the languages supported by Google Protocol Buffers (most languages are supported).
The Composition tab only appears for specifications marked as composite devices. A compositedevice has a Device Element Schema which provides the structure for nesting other devices.The schema includes Device Slots and Device Units. Device slots are locations where a device can be ‘plugged in’ to the composite device. Device units are named containers which mayhold their own slots or more nested units. There is no limit to the number of levels of nestingallowed. The device units act like folders in a file system, so any nested slot may be referencedby a path of unit names followed by the slot name. For instance default/serial/com1 refersto the com1 slot on the serial unit, which is in turn nested in the default unit.
When a device of the given specification type is added to the system, nested devices may be registered to any of its slots. When commands are sent to one of the nested devices, SiteWheredetermines the parent composite (gateway) device and sends the command to the parent, which willin turn relay the command to the nested device.
SiteWhere devices represent physical devices that can interact with the system. Registered devicescan send events to SiteWhere via configured event sources or by invoking REST services. SiteWherecan, in turn, send commands by way of a command destination that delivers command data to the physical device.
Choose Devices from the Devices dropdown in the navigation bar to open the device list page. All existing devices are listed with the ones most recently created at the top of the list:
To create a new device, click on the Add New Device button at the top of the listpage. To change an existing device, click the edit icon at the right side of the entry.The following sections cover information needed to create or edit a device.
The Device Details tab includes basic information about a device.
The Specification tab is used to choose the device specification that describesthe device. The specification is used to infer the type of device hardware,whether the device can contain nested devices, and which commands may be sentto control the device.
Each device can have arbitrary metadata attached to its primary data to provideadditional information during processing. For instance, a particular device mayreceive commands via SMS, in which case the SMS phone number should be savedwhen the device registers with SiteWhere. The metadata is available during eventand command processing so the SMS phone number can be extracted and used to deliver commands to control the device. Metadata is stored as name/value pairson the device definition and may include complex structures such as XML or JSONpayloads.
SiteWhere is designed to manage and interact with a large number of devices, so itis important to be able to target specific groups of devices based on criteria.On the device list page, clicking on the Filter Results button opens adialog that allows criteria to be specified to narrow the list of results.
The sites tab allows devices to be filtered based on the site they are associatedwith. The two choices include:
Do not filter by siteInclude only devices that are associated with a given site.
The specifications tab allows devices to be filtered based on the device specificationthat they implement. The two choices include:
Do not filter by specificationInclude only devices that implement a given specificationLimiting results to devices that implement a specification allows all devices of a given type to be targeted. It also adds a Batch Command button to thetoolbar, allowing a command to be executed as a batch operation for all of thedevices that meet the criteria. Other criteria may be applied in addition tothe specification to limit the scope of devices affected by the command.
The Groups tab allows search results to be limited based by whether devicesare contained in specific device groups. The choices for group filtering include:
Do not filter by groupInclude devices that belong to a particular groupInclude devices that belong to groups with a given roleThe group filter criteria is applied in addition to any other criteria so, forinstance, you can choose a specification and a group to choose only devices of a given type in the group. You can then click Batch Command to send a command toonly those devices.
The Created Date tab allows search results to be limited by the date a devicewas added to the system. The choices for filtering by created date include:
Do not filter by created dateInclude devices created in the last hourInclude devices created in the last dayInclude devices created in the last weekInclude devices created before a given dateInclude devices created after a given dateInclude devices created between two datesThe created date filter criteria is applied in combination with other filters so,for instance, you can choose devices in a group that implement a given specificationand were created in the last week.
The Other Options tab is a catch-all for other criteria that can be used to filter the device list.
Currently, the only option available is filtering devices that are already assigned. Choosing this option will return only unassigned devices. Examples ofusing this option include looking for devices of a given type that are notassigned yet or looking for devices in a group that are not assigned yet.
Note that excluding assigned devices will prevent being able to send a batch device command invocation because commands can only be sent to assigned devices.
From the device list page, clicking on the green arrow to the right of an entry opensthe device detail page. As shown in the image below, the device detail page contains the base device information including the current asset assignment if assigned.
The Assignment History tab shows the current and all previous asset assignments forthe given device. Assignments are ordered with the most recent assignments at the top.Clicking on the green arrow at the right side of an assignment opens the details pagefor the assignment including the complete event history while assigned to the given asset.
The Composition tab is only shown for devices that use a specification marked ascomposite rather than standalone. This tab allows nested devices to be assigned to slotsin the device element schema defined in the specification. Clicking the + to theright of a given slot brings up a dialog to choose the device that will fill the slot.Once a device has been assigned to a slot in a composite device, commands will be sentto the parent device rather than the nested device.
Device assignments represent the association of a device with a site and (optionally) a physical asset. For example, a badge device can be assigned to an office building and a particularperson in that building. Events received for a given hardware id are recorded under thecurrent device assignment for that device. In the case of the badge example, there wouldbe a separate event trail for each person the badge was assigned to.
If a device does not have a current assignment, an Assign Device button will appear inthe asset portion of the device entry as shown below:
Clicking the button opens a dialog that allows the device to be assigned. TheAssignment Details tab shows the hardware id for the device that willbe assigned.
Clicking the Asset Association tab allows an asset to be associated with the device.If the Associate Asset checkbox is left unchecked, the device will not be assigned to an asset.Otherwise, the list of asset providers is shown in a dropdown. Choose an asset provider andthen choose an asset from the list for that provider.
Clicking the Metadata tab allows metadata to be created for the assignment. An example ofassignment metadata is a ‘valid through’ date for the badge. This can be used by the system tofire an alert if the badge is used beyond a given date.
Clicking the Assign button at the bottom of the dialog will create the assignment.
The assignment detail page can be accessed from the Assignments tab for a site or fromthe Assignment History tab in the device details page. In both cases, clicking on thegreen arrow at the right of the assignment entry navigates to the View Assignment page.
The View Assignment page contains all of the event data related to the given assignment.The Locations, Measurements, Alerts, and Command Invocations tabs displayevents of each given type for the assignment.
Clicking the Command Invocations tab displays the list of commands that have been issuedto the device over the duration of the assignment. Click the Invoke Commmand buttonto issue a new command to the device. Note that the list of available commands is basedon the device specification for the device in the assignment. Each command has a list ofparameters and the command dialog allows the parameters to be filled in before sending the command.
Clicking the Schedule tab allows the command to be executed on a schedule rather thaninvoking it immediately. A scheduled job will be added for the command and a new commandinvocation will be generated every time the schedule fires. The job can be cancelled bynavigating to the Scheduled Jobs page and deleting the job.
If the command is not scheduled, clicking the Invoke button will immediately create a new command invocation event, storing the event for the assignment and sending the command to the device based on the server provisioning configuration.
Device groups are used to create an association between related devices. A device can belongto any number of groups and there is no limit to the size of a group. Device groups can alsocontain other device groups. Each element (device or subgroup) in a device group can havezero or more roles assigned. This allows external applications to query a device group andget a list of devices that serve a given role or roles, then take actions such as issuingcommands or updating metadata.
Clicking on the Device Groups entry in the Devices dropdown in the navigation bar opens the device groups list page. All existing device groups are listed with the ones most recently created at the top of the list:
To create a new device group, click on the Add New Device Group button at the top of the listpage. To change an existing device group, click the edit icon at the right side of the entry.The following sections cover information needed to create or edit a device group.
The Group Details tab includes basic information about a device group.
The Roles tab allows a list of roles to be associated with a device group. Roles are usedto allow groups to be looked up in different contexts. For instance, a device group mayhave a list of temporary badges for tracking people. Another device group may contain the list of badges that belong to employees on the first floor. Both groups may have a commonrole of ‘badgeList’. Querying the SiteWhere services for groups with a role of ‘badgeList’will return both groups. Batch command invocations allow device commands to be targetedat device groups to allow for bulk operations.
The Metadata tab allows extra metadata to be associated with a group. The extra informationwill generally be application specific. For instance, a temporary badge group may have extrametadata for the building phone number or address where the badges are in use.
Batch operations are actions that operate on multiple devices, executing asynchronouslyand providing a mechanism for monitoring progress over time. Examples of batchoperations include executing commands on a large number of devices or applyingfirmware updates to a group of devices. The batch operation manager is responsiblefor taking a batch operation request and breaking it out into the actions necessaryto complete the goal. Since batch operations can result in a large load on the system,the batch operation manager allows for throttling the execution of operations so thata reasonable load is achieved when dealing with thousands or millions of devices.
Clicking the Batch tab in the navigation bar opens the batch list page.All batch operations are listed in reverse chronological order.
Commands can be invoked as batch operations by navigating to the device list page, specifying criteria to limit the devices that will be affected, then clicking the Batch Command button in the toolbar. Note that commands canonly be executed on devices that implement the same specification, so the filter criteria must limit the device list to a single specification. Once a batch command has been executed, it will appear on the batch opearation listpage. Clicking on the arrow to the right of the operation entry will navigate to the batch command invocation details page as shown below:
The banner at the top of the page incudes information about the batch commandinvocation. The command that was executed is shown along with the values passedfor any arguments. The other fields are summarized in the table below:
Below the header is a list of the batch operation elements. These correspondto the individual commands that were invoked on devices. Each entry indicatesthe hardware id of the affected device, the processing status (indicating whethera command invocation was created successfully), the processed date, anda link to the command invocation event that was generated.
Schedules allow SiteWhere functionality to be executed in the future or in a recurring fashion. SiteWhere currently uses scheduling for command invocationsand batch command invocations, but other areas of functionality will be added in the future. Schedules are broken down into two basic types: simple and cron-based.
Simple schedules specify a delay interval and number of times an operation is to beexecuted. An example of a simple schedule is ‘fire a command to blink a device LEDevery minute and stop after twenty repetitions’.
Cron schedules are more complex, but allow for advanced scheduling. They supportconditions such as ‘fire a command to update firmware at noon every third Monday of the month except where that falls on a holiday in a given calendar’.The default SiteWhere schedule manager is based on theQuartzscheduler, so expressions should be Quartz-compatible.
Both schedule types support start and end dates for determining the interval withinwhich they are active.
Clicking on the Schedules dropdown in the navigation bar and choosing Schedulesopens the schedule list page. All existing schedules are shown in alphabetical orderof schedule name.
To create a new schedule, click on the Add New Schedule button at the top of the listpage. To change an existing schedule, click the edit icon at the right side of the entry.The following sections cover information needed to create or edit a schedule.
The Schedule Details tab includes information about a schedule.
The following fields are common to both simple and cron-based schedules:
The following fields only apply to simple schedules:
The following fields only apply to cron-based schedules:
SiteWhere users represent entities authorized to use the system. User credentials are usedto log in to the administrative console and are required for accessing the REST services.When performing create/update operations on SiteWhere entities, the username of theauthenticated user is stored to indicate who performed the action.
When logged in to the administrative application, clicking on the active user dropdownin the top-right corner will offer a choice of Manage Users if the current userhas permissions to administer users. The users list page shows all existing users ordered alphabetically by username.
To create a new user, click on the Add New User button at the top of the list.To change an existing user, click the edit icon at the right side of the entry.
The User Details tab includes basic information about a user.
The Permissions tab allows user permissions to be specified. User permissionslimit access to parts of the system.
The Metadata tab allows extra metadata to be associated with a user.
SiteWhere tenants allow multiple customers run side-by-side on a single SiteWhere instance.Each tenant has its own datastore and processing pipeline so that there is no interminglingof data. Each tenant has its own configuration that extends the global configurationallowing all facets to be customized on a per-tenant basis.
At least one tenant is required in a SiteWhere instance. If using the sample data populated from the global user model initializer, a tenant with id default will automatically beadded.
When logged in to the administrative application, clicking on the active user dropdownin the top-right corner will offer a choice of Manage Tenants if the current userhas permission to administer tenants. The tenants list page shows all existing tenants ordered alphabetically.
From the tenant list page, clicking on the green arrow to the right of a tenant opensthe tenant detail page. The tenant detail page shows the status of the given tenant andother information based on that status.
A tenant that is in a stopped state will have action buttons for editing, deleting, orstarting the tenant. Changes can only be made to a tenant when it is in a stopped state.
A tenant that is in a running state will have an action button for stopping it. No otheroperations can be performed while a tenant is running. The detail page also shows informationabout the active configuration for a running tenant. The information includes a tree viewof the system components and their states. It also includes a view of the active configurationin XML format.
