Source Maps
A source map defines how to read and write data points for a Source. It provides a structured description of each data point, including the point name, metadata such as units, and the specific address used to access the point value.
By standardizing point definitions, source maps enable consistent and accurate data access across different devices and projects, simplifying integration and reducing configuration effort.
Structure
Source maps are composed of two parts:
- Source metadata such as vendor and model
- Points list that defines the available data points
Source Fields
The available source level fields are:
| Field | Required | Description |
|---|---|---|
| Name | Yes | Human readable name of this source |
| Type | Yes | Protocol for this source |
| Vendor | No | Vendor who manufactures this source |
| Model | No | Model number of this source |
| Description | No | Human readable description of this source |
Point Fields
The available point level fields are:
| Field | Required | Description |
|---|---|---|
| Name | Yes | Human readable name of this point |
| ID | Yes | Unique ID of this point within this source map |
| Address | Yes | Protocol specific address to access this point |
| Type | Yes | Semantic type for this point |
| Unit | No | Unit for this point value |
| Enum | No | List of states for enumerated point values |
| Formula | No | Formula to use for calculated points |
| Description | No | Human readable description of this point |
Point Properties
Points may also carry properties that qualify what the point represents. Each accepts a fixed set of values:
| Property | Values | Description |
|---|---|---|
| Schedule | occupied, unoccupied,
standby |
Which occupancy schedule the point applies to |
| Mode | heating, cooling, warmup,
cooldown |
The operating mode the point is associated with |
| Limit | min, max |
Whether the point is a minimum or maximum limit |
| Modifier | alarm, differential,
effective, offset, runtime,
static |
Additional qualifier describing the point |
These distinguish points that share a semantic type. A zone
temperature setpoint for occupied hours and one for unoccupied hours are
both zone_air_temp_sp, separated by their
Schedule value. Likewise a heating setpoint and a
cooling setpoint are separated by Mode.
Each property also contributes a tag to the point’s ontology, so a
point with schedule of occupied picks up the
occ Haystack tag.
A value outside the accepted set is rejected.
Source vs Calculated Points
Each point in a source map is either a source or a calculated point:
A source point stores live or historical data from a device or system, using a protocol-specific address to read and write values.
A calculated point computes its value on demand using a formula, optionally referencing other points in the same source map.
Only calculated points may include a formula, and their address field
must begin with the calc. prefix. See Calculated Points for
more information.