These concepts will help you better understand what everything means in the SIB. Below is a short summary of each concept.
- sensemetrics Thread
- Derived Metrics
- Integration Definitions
- Code Hooks
The Thread is a plug and play data aggregation instrument that is used to power and connect any device/sensor. See here for more info.
A device that is associated with a sensemetrics Thread connection, is something that is connected to the Thread via one of the two device ports. That device can then have multiple sensors associated with it. An example of a device is a Geokon datalogger or a SlideMinder or a Vaisala Weather Station. A device is something the Thread communicates with over serial or USB to obtain readings or observations.
A sensor is associated with a device and represents the data or observations in sensemetrics. A single device can have multiple sensors. Every sensor has an associated set of metric and unit pairs. An example of a sensor is a temperature sensor that records observations in units of Celsius. Another example of a sensor is a vibrating wire piezometer that records frequency in hertz and temperature in Celsius.
An observation is a numerical reading or group of readings for a sensor with an associated timestamp. An example of an observation is 75.6 degrees Fahrenheit at December 10, 2019 for a temperature sensor. Every observation has an associated set of metrics and units and a unique timestamp. Retrieving observations is a key goal of a successful device and sensor integration. Observations on the sensemetrics platform are then used for downstream analytics and processing and drive features such as reporting, alerting, and graphing.
A metric is a representation of a measurement. Examples include temperature, velocity, frequency, and x, y, z position. All metrics have a unit. A raw metric is the metric that is directly reported by the device without any changes or conversions. See Metrics and Units Reference for a full list of available metrics.
A derived metric is a metric that is calculated based on a given raw metric using an algorithm. An example of a derived metric is velocity. Given position and time, velocity can be calculated using an algorithm. See Metrics and Units Reference for a full list of available metrics.
A property is a key-value pair associated with a device or sensor. These can include things such as serial numbers, names, or any arbitrary key-value pair that describes the device or alters its integration behavior. These can also include site installation specific values such as collar elevation, sensor depth, or calibration factors for a vibrating wire. Keys are 'strings' and values can be most any type, including integers, strings, booleans, longs, doubles, or maps. Properties usually appear on a device or sensor's config form for editing or viewing. See the PropertyTypes Reference for a full list of available PropertyTypes.
A control is a UI component that appears on a form and can be declared using YAML. Controls can be added/removed to/from forms at runtime. These include such things as text boxes, text areas, select drop-downs, buttons, modals, and other common UI components. A control is associated with Properties and is two-way bound to those properties. See UI Controls for more info.
An algorithm is used to calculate derived metrics which are metrics that are calculated from a raw metric. An example of an algorithm is the calculation of pressure for a vibrating wire given frequency and the manufacturer's associated calibration factors. Another example of an algorithm is the calculation of velocity given position and time.
A category is an arbitrary grouping of SIB integrations. For example, a category might represent all of the device integrations made by a particular manufacturer. A different category might represent all vibrating wires that are strain gauges. Categories can be altered at runtime and members can be added/removed at any time.
SIB integration definitions describe how to communicate with any device or sensor and all of the metadata associated with that device or sensor. These definitions are exported/imported to/from the sensemetrics platform as a single YAML file. The SIB UI builder that is part of the sensemetrics web application is a tool to assist in the building of these integration definitions. Integration definitions can also be created using any other tool to create the YAML file and then inserted into the sensemetrics platform using a REST API. Integration definitions specify the following:
- The code to interact with the device over serial or USB
- Any metadata associated with the device or sensor, e.g. icons, default sampling rates, baud rate
- The UI controls associated with the config form for the device or sensor
- The algorithm code to calculate derived metrics from raw metrics
A device or sensor instance is a device or sensor at a specific customer site or out in the field. All instances have an integration definition associated with it. An example of a device integration definition is a Geokon Data Logger 8002, whereas an example of a device instance is the specific Geokon Data Logger 8002 that is installed at a customer site in Brazil with a specific latitude/longitude location. Any change to a device or sensor integration definition is immediately pushed out to all instances of that device or sensor integration definition.
- api - this object is available in all integrations and includes an assortment of commonly used methods to assist with development
- log - this object is available in all integrations and is a basic logger that is useful for debugging and printing out diagnostics
YAML is a popular human-readable data-serialization language. It is very similar to JSON and it is commonly used for configuration files and in applications where data is being stored or transmitted. YAML is the format that all SIB integrations are stored as. An entire device integration is encapsulated in a single YAML file. Similarly, an entire sensor integration is encapsulated in a single YAML file.
Templates are canned snippets of code or YAML that make it easy to insert code or UI controls in an editor pane. The template menu appears on the right side of the editors as part of the integration builders. Clicking a template will automatically insert the relevant snippet at the cursor in the editor pane.