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 |
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.
CSV Format
Source maps can be exported and imported from projects as CSV and MS Excel documents, with the first data row containing the source metadata and the following rows detailing the point list.
The id, addr, unit,
enum, and forumla columns are left blank for
the source row, while vendor and model are
left blank for point rows.
| name | id | type | addr | unit | enum | forumla | vendor | model |
|---|---|---|---|---|---|---|---|---|
| Kaiterra SE200 | bacnet | Kaiterra | SE200 | |||||
| Temperature | p.1 | air_temp_sensor | ai.1 | °C | ||||
| Humidity | p.2 | air_humidity_sensor | ai.2 | % | ||||
| CO2 | p.3 | co2_sensor | ai.2 | ppm | ||||
| PM2.5 | p.4 | ai.4 | μg/m³ | |||||
| PM10 | p.5 | ai.5 | μg/m³ | |||||
| TVOC | p.6 | ai.6 | ppb | |||||
| Temp °F | p.7 | calc.1 | °F | $1 * 9 / 5 + 32 |
Field to CSV Column Name Mapping
The following table shows each field and its respective column name in CSV:
| Field | CSV Column Name |
|---|---|
| Name | name |
| ID | id |
| Address | addr |
| Type | type |
| Unit | unit |
| Enum | enum |
| Formula | formula |
| Vendor | vendor |
| Model | model |
| Description | desc |