Every WattDepot server installation requires the definition of a single administrator (whose name by default is "root" but which can be changed by the installer or when the server is run) and associated password (with no default value, and which must be specified by the installer). This administrator is automatically placed in the predefined organization named "admin", which grants the administrator special capabilities not available to users. These capabilities include the ability to:
Users, sensors, sensor groups, collectors, depositories, and measurements all belong to a single "organization".
Organizations create a namespace for WattDepot entities. For example, a single WattDepot server might hold data from two
organizations, "University of Hawaii" and "Hawaii Pacific University". Organizations are defined with an id, which is a
short alphabetic abbreviation suitable for identifying the organization in URLs. The organization "University of Hawaii"
might have the id "uh" and "Hawaii Pacific University" might have the id "hpu".
The organization id is generally the first element of a WattDepot API call. For example, to retrieve information about the University of Hawaii repositories, you might invoke:
GET http://server.wattdepot.org/wattdepot/uh/depositories/
To get Hawaii Pacific University's sensors you would use:
GET http://server.wattdepot.org/wattdepot/hpu/sensors/
You must be logged in as an HPU user to see HPU's entities.
In general, you can only manipulate entities created within your organization. There is one exception: the pre-defined organization with the id "public" which defines "global" entities such as measurement types and sensor models.
To use a WattDepot server, begin by requesting a user name and password from the server's administrator. You must also indicate if you are joining an existing organization or if you wish a new organization to be created on the server. Once you have obtained these credentials, you can:
All of these manipulations occur within your organization.
Sensors represent a device that measures (or predicts) a physical phenomena. Sensors have the following properties:
Note that some physical devices can measure multiple phenomena (such as energy from multiple floors, or both energy and power, or energy and temperature). In these cases, the physical device will be represented by multiple Sensors.
Users often find it convenient to request aggregations of sensor data. For example, a user might wish to know the energy consumed by a building, which might involve aggregating the energy measurements associated with Sensors located on each floor of the building.
By defining a Sensor Group and associating individual Sensors with it, users can obtain aggregate measurements.
All Sensors in a Sensor Group must collect data of the same Measurement Type.
Collectors are processes that contact a Sensor, obtain Measurements from it, then store this data in a WattDepot server.
One implementation of a Collector might be a software program that uses the IP address of a Sensor to contact it and request a measurement value. After obtaining that value, it then contacts a WattDepot server and uses the HTTP API to store that value in the server.
An alternative implementation of a Collector is a person who reads a meter manually to obtain a measurement, then uses a GUI interface to a WattDepot server to store that value.
In order for a Collector to do its job, it must be able to obtain information about the Sensor it is supposed to contact. It is also useful for the Collector to know how often it should collect data, what data to collect, and where to store it in the server. WattDepot represents this information with the "Collector Process Definition" entity.
In prior versions of WattDepot, the collector software programs hard-wired information about when, where, and how often to collect data into their source code. In this version, we expect Collector programs to first query the WattDepot server to obtain their process definition, and use that definition to determine what to do. By representing the task associated with a Collector in the server explicitly as process definition, the server can provide significant new capabilities to users. For example, a server can now understand how frequently to receive data from a Collector, and signal the user if data is not being received as expected.
WattDepot provides all the units of measurement provided by the JScience API. Supported units include both SI Units and Non-SI Units.
In addition, it is possible in WattDepot to define new Measurement Types. Adding a new Measurement Type requires changes to the source code and rebuilding of the system.
Measurement Types are members of the "public" organization, which makes them visible to all users of a server.
Depositories store measurements made by Sensors and collected by Collectors.
Depositories can store Measurements made by different Sensors and different Collectors, but all Measurements must be of one and only one Measurement Type.
Measurements are made by Sensors and collected by Collectors. A Measurement includes the following information:
Sensors can either measure phenomena as they occur, or predict phenomena that may or may not occur. Sensors can provide measurements for phenomena with a timestamp in the future. It is the responsibility of users to check the sensor associated with a measurement to determine its validity and meaning.
Interpolated Values are different from Measurements. Measurements are the "raw data" in WattDepot. For example, a Collector may obtain a power measurement from a Sensor every 10 seconds.
Unfortunately, WattDepot users often want to know a value at a specific timestamp regardless of whether or not a Collector has obtained a Measurement at that timestamp. For example, a user might want a visualization that shows the power being consumed by a building every hour on the hour.
For this use case, WattDepot provides Interpolated Values. Interpolated Values differ from Measurements in that WattDepot will interpolate in the cases where there does not exist a Measurement corresponding to the precise timestamp requested by the user. (In real life, this is the case virtually all of the time).
WattDepot supports two kinds of Interpolated Values: point values and difference values.
Point values are calculated for a single timestamp. If there exists a Measurement corresponding to the timestamp, WattDepot will return that value. If the timestamp is between two Measurements, WattDepot calculates the linear interpolated value and returns it. If the timestamp is not bounded by two Measurements, then WattDepot will return an error.
For difference values, WattDepot gets the point values for the starting timestamp and the ending timestamp and returns the difference.
It is the responsibility of the user to assess the validity of Interpolated Values returned by WattDepot. WattDepot will return the type of Interpolated Value the user requests even if it makes no physical sense.
WattDepot will store all the measurements collected. However the number of measurements can grow quickly. It is often the case that the user is not interested in old fine grained data, so we created the concept of Measurement Pruning. Measurement Pruning Definitions (MPD)s allow the user to define the desired frequency of measurements for old data.
For example, in the Kukui Cup, we want energy and power data every 15 seconds, but only desire a five minute frequency for data that is older than 1 day. This greatly reduces the number of measurements WattDepot needs to store.
MPDs have:
See the Quick Start guide for information about adding Depositories, Sensors, and Collector Process Definitions.
The administration UI is fine for adding a few items. If you want to add many sensors you should use the Organization Domain tool. WattDepot provides a tool for defining an organization's domain model in a CSV file. Then you can upload the file to the WattDepot Server, thus saving you lots of tedious web clicking and typing.
The CSV file has the following format.
The Depositories section should start with a comment showing the structure of each line defining the depositories. The example comment is:
# Depositories: 'Depository', Name, MeasurementType Name, MeasurementType Unit, OrgId
The lines defining the depositories must have the following information in the given order:
The Organization Id
Depository,Power,Power (W),W,uhm
Defines the 'Power' depository with the MeasurementType Power (W), the unit is W and the organization id is uhm.
We recommend you use the Organization Administration UI to create your Depositories since the MeasurementType Unit is often a non-standard character like the degree symbol.
The Sensors section should start with a comment showing the structure of the lines.
# Sensors: 'Sensor', Name, URI, ModelId, OrgId, num properties, prop1.key, prop1,value, ...,
The lines defining the sensors must have the following information in the given order:
Sensor,Honolulu NOAA,http://w1.weather.gov/xml/current_obs/display.php?stid=PHNL,noaa-weather,uh,0,
Defines the Honolulu NOAA sensor of type noaa-weather and 0 properties
Sensor,Lokelani 10th Telco,http://192.168.105.39,shark,uh,1,registerName,Student_Lounge
Defines the Lokelani 10th Telco sensor of type shark with 1 property, whose key is 'registerName', value of 'Student_Lounge'.
The Sensor Groups should start with a comment showing the definition of the Sensor Group lines.
# SensorGroups: 'SensorGroup', Name, OrgId, num sensors, sensorId1, sensorId2, ...,
The lines defining the sensor groups must have the following information in the given order:
SensorGroup,Ilima A,uh,2,ilima-4th-telco,ilima-4th-lounge,
Defines the 'Ilima A' Sensor group consisting of two sensors on the fourth floor.
SensorGroup,Ilima Total,uh,10,ilima-4th-telco,ilima-4th-lounge,ilima-6th-telco,ilima-6th-lounge,ilima-8th-telco,ilima-8th-lounge,ilima-10th-telco,ilima-10th-lounge,ilima-12th-telco,ilima-12th-lounge,
Defines the 'Ilima Total' group with 10 sensors.
The Collector Process Definitions section should start with a comment showing the format of the CPD lines.
# CollectorProcessDefinitions: 'CollectorProcessDefinition', Name, SensorId, Polling, DepositoryId, OrgId, num properties, prop1.key, prop1.value, ...,
The CPD definition lines have the following format:
CollectorProcessDefinition,Ilima 4th Telco Energy,ilima-4th-telco,15,energy,uh,0,
Defines the 'Ilima 4th Telco Energy' collector using the ilima-4th-telco sensor and the energy depository with a polling interval of 15 seconds with no properties.
CollectorProcessDefinition,Honolulu Temperature,honolulu-noaa,3600,temperature,uh,1,registerName,temp_f
Defines the 'Honolulu Temperature' collector using the honolulu-noaa sensor and the temperature depository with a polling interval of one hour or 3600 seconds. It also has one Property key = 'registerName', value = 'temp_f'.
# MeasurementPruningDefinitions: 'MeasurementPruningDefinition', Name, DepositoryId, SensorId, OrgId, ignore window days, collect window days, minimum gap seconds