Heat Network Protocol

MQTT protocol applied to Heat Networks.

See also https://github.com/heatweb/heat-network for the GitHub project hosting the protocol.

network_id / publisher_id / device_id / data_group / key = value

myHeatNetwork/plantroomController1/primaryHeatNetwork/stat/percentDistributionLossesJanuary2019 = 10.34 (network distribution losses)

myHeatNetwork/plantroomController1/boiler1/alarm/tOut = low temperature (boiler low temperature alarm)
myHeatNetwork/plantroomController1/boiler2/alarm/tOut = ok
myHeatNetwork/plantroomController1/boiler2/dat/run = 1

myHeatNetwork/ab34c23Z/hiu0198984733686/dat/fC = 3.2 {HIU, tap flow rate)

myHeatNetwork/ab34c23Z/hiu0198984733686/settings/prepayRun = 1 {HIU, prepay isolation)
myHeatNetwork/ab34c23Z/hiu0198984733686/set/prepayRun = 0 {HIU, command to isolate on prepay)

myHeatNetwork/ab34c23Z/hiu0198984733686/hm/kwh24h = 13.3 {HIU heat meter, energy used over past 24 hours)

myHeatNetwork/ab34c23Z/blockB2/hm/kwh24h = 1204.3 {residential building heat meter, energy used over past 24 hours)

To Consider

The starting point for the unified heat network protocol is what the industry has already - the SAP Product Characteristics Database (PCDB).

• http://www.ncm-pcdb.org.uk/sap/filelibrary/pdf/Applications/APPF-01---Application-guide-for-entry-of-heat-network-performance-data-in-SAP-PCDB---V1.0.pdf

The aim is to expand this data schema to create a framework that enables the description and communication of any data concerning heat networks, from the overall network performance data down to the setpoints on individual components.

At the same we wish to ensure traceability of data, as well as the ability to filter and group data, and to enable assignment of read or write permissions to clients.

To achieve this we are using a standard 5 level MQTT topic structure, along with the associated JSON structure.

We also want to look at Project Haystack, in an attempt to make the protocol compatible with as many other systems as possible.

• Naming policies want to be descriptive, but short in order to save data during transmission.
• Haystack used camel case naming, where names start in lowercase, with a capital used for the start of each 'tag'. e.g. primaryInTemp, (or preferably) tH
• MQTT topics (our filing system) want to follow a structured approach that provides a high degree of filtering.
• Once a complete working data description for a piece of equipment has been defined, they should be numbered to standardise Modbus Registers where used

Extended Protocol

MQTT topics can have more layers, however doing so makes unified handling more complex.

The protocol will be updated to allow for more than the 5 standard layers.

The only rule is that the 6th (first additional topic) is an attribute, goes at the end, and replaces the standard value with a value attribute.

network_id / publisher_id / device_id / data_group / key / attribute = attribute value

myHeatNetwork/ab34c23Z/hiu0198984733686/dat/fC/value = 3.2
myHeatNetwork/ab34c23Z/hiu0198984733686/dat/fC/title = HIU, tap flow rate
myHeatNetwork/ab34c23Z/hiu0198984733686/dat/fC/units= ltr/min

Further levels go at the start, and will normally be used to describe complex heat network heirarchy.

allNetworks/London/KT4/myHeatNetwork/ab34c23Z/hiu0198984733686/dat/fC/value = 3.2

Uses for Data Structure

• Heat Network performance monitoring
• Device monitoring and alarming
• Specification of operational parameters
• Commissioning checks
• User/engineer commands
• Connecting isolated systems to add new functionality (e.g. billing & hiu control)
• Combining data for sanity checks (e.g. heat meter sensors & hiu sensors for tamper alarming)

Tags and Camel Case

The point of this protocol is to standardise naming, so it is important to try as best as possible to adhere to a code, so it is possible to deduce a new name from existing practices.

Project Haystack uses tags and camel casing to deduce names. Camel case uses lower case lettering, with the start of each new tag in uppercase, making it possible to split the name into parts. As many systems, including MQTT, are case-sensitive, it is important to adhere to the strict naming.

anExampleOfACamelCaseName

We have adopted the practice of using the first tag in a name for the units of the name, if there is one. Some examples are:

The second tag (or further tags) would then be the noun the prefix belongs to:

Sometimes an object could be described by one or more tags, and the context of use may then decide the selection.

Prefix and noun tags are combined to form complete tags.

Further tags or numbering can be added where needed.

MQTT Topic Structure

MQTT topics are similar to directories and files on a computer. They describe where data goes, as well as the type of data.

network_id / node_id / device_id / data_group / key = value

We have, through trial and error, arrived at this 5 level structure to enable permissions to be granted based on the network, the device or system in question, and the type of data.

The node_id refers to the network device (typically running Node-RED) that connects to a MQTT server, as as such is the MQTT user name. A publishing device may collect data for one or more devices.

The network_id and device_id form the basis of global device identification, and must be a unique combination. Different nodes can then post data on this device.

The structure translates into two forms of information - FACTS and OPINIONS.

FACTS are provided by the Node to which the device runs on physically. OPINIONS are data provided by other nodes (about the device), such as calculations and statistics. Alarms, for example, can either come from the device itself (facts), or can be generated by a remote server watching data and generating further alarms (opinions). This also corms the basis of redundant data points, which would be an opinion based on facts from, for example, redundant sensor systems such as an HIU and a heat meter.

A simple 5 (minus node = 4) level structure also translated into browsers and JavaScript (what you are looking at now), with it been possible to fix references in 'web pages' to a topic. For example, #n-boilers-dat-tF is the common reference in objects to the common boiler flow temperature. It can be referenced in graphics (SVG) as a class typically, allowing text and colours to be altered to refer to the data point. By following the standardised structure, graphics objects can be reused, and code can be common across applications. We ignore the node_id as it is part of the MQTT subscription process that decides where (which node) information comes from. It is still possible to go off-piste and refer to nodes, indeed this extra 'space' for custimisation.

Data Groups

Example statistics:

network_id/+/network/stat/# (network stats)

network_id/+/+/stat/# (all stats)

network_id/+/subSt/stat/# (substation stats)

network_id/+/boilers/stat/# (boiler stats)

MQTT Permissions

Topics allow read or write permissions to be assigned to users on an MQTT server based on the topic levels and wildcards.

A device (publisher_id) publishing data to the server would typically have read and write permissions for

network_id/publisher_id/#

The # covers all further topic sub-levels.

One could allow a maintenance company to subscribe to warnings, alarms, from all devices on a network by giving read permission for

network_id/+/+/alarm/#
network_id/+/+/warning/#
network_id/+/block_id/stat/htmlReport

The engineer would receive all alarms and warning generated by the system (to a mobile app for example) along with the full topic, thereby providing tractability to the source of the alarm through the network and device levels in the topic structure.

PCDB Fleld 2 Example

Field 2 of the PCDB refers to the heat **network '**pcdb', version Number.

network_id/publisher_id/network/pcdb/verN = value

pcdb_921/ab45de1998ca/network/pcdb/verN = 2

PCDB Fields

The SAP Product Characteristics Database (PCDB) stores performance data for heat networks.

• http://www.ncm-pcdb.org.uk/sap/filelibrary/pdf/Applications/APPF-01---Application-guide-for-entry-of-heat-network-performance-data-in-SAP-PCDB---V1.0.pdf

The following is taken from the PCDB, with MQTT topic tags added using abbreviated camel form.

The full topic would start with:

network_id/publisher_id/network/pcdb/mqtt_key

Where network_id is the network index number (= field 1), and publisher_id is the user name for access to the database.

| Date and time this record was created or last amended by the database administrator. | dateTime | | 4 | | Description of network

(up to 255 chs)

| A short description identifying the dwellings to which the network version applies.

Where the network is constructed in phases this may also indicate which phases are connected.

| des | | 5 | X | Validity end date

(yyyy/mmm/dd)

| The last day of validity of this data record. Dwellings assessed after this date use a

data record with a higher network version number (in the case of new dwellings the applicable assessment date is that of the as-designed assessment). Blank if there is no record with a higher network version number.

| dateValidUntil | | 6 | | Community heat network name

(up to 50 chs.)

| The name by which the community heat network is known. | name | | 7 | | Postcode of the Primary

Energy Centre (up to 8 chs)

| The postcode of the energy centre providing heat for the network. Where there is

more than one energy centre, it is the postcode for the energy centre supplying the largest amount of heat

| postcodeEc | | 8 | | Locality

(up to 35 chs.)

| The locality in which the community heat network is situated. May be blank. | lacality | | 9 | | Town name

(up to 30 chs.)

| The post town nearest to the community heat network. | town | | 10 | | Administrative area

(up to 30 chs.)

| The administrative area in which the community heat network is situated. May be

blank.

| areaAdmin | | 11 | | Date of initial operation

(yyyy/mmm/dd)

| The date on which the energy centre was commissioned (or re-commissioned if the

network is extended) to serve all dwellings included in the assessment. Blank if it is not yet operational or if the assessment includes dwellings not yet connected.

| dateOn | | 12 | | Total number of dwellings

included (up to 5 digits)

| The total number of dwellings included in the assessment of the heat network. | nPropTotal | | 13 | | Number of flats (up to 5

digits)

| The number of flats included in the assessment of the heat network | nFlats | | 14 | | Non-domestic floor area

connected (up to 6 digits)

| The floor area of any non-domestic buildings connected to the heat network. | faNonDom | | 15 | | Total number of existing

dwellings (up to 5 digits)

| The number of dwellings which have been constructed. This can be less than the

number in field 12 if the assessment included dwellings not yet constructed.

| nPropExist | | 16 | X | Service provision

(1 digit)

| Service provision, encoded as: 1 space and water heating; 3 space heating only;

4 water heating only. If a network has separate systems for space heating and water heating, there will be a record for each.

| serProv | | 17 | X | Provisional or actual data

(1 digit)

| Whether the record represents provisional (estimated) data or actual recorded data,

encoded as 1 or 2 respectively. Provisional data may be assigned to new networks for which recorded data are not yet available.

| provAct | | 18 | X | Year

(4 digits)

| The calendar year to which the data relates. Blank if provisional data. | year | | 19 | | Heat metering on supply to

network (1 digit)

| Whether the heat supplied to the network from the energy centre is metered. 1 for

yes. 0 for no

| isSupplyMetered | | 20 | | Total MWh of heat per

annum supplied to network (up to 6 digits)

| The annual amount of heat supplied to the network by the plant in the energy centre. |

kwhYAvr kwhJanAvr kwhFebAvr kwh2018 kwhJan2018

| | 21 | | Total MWh of heat per

annum delivered to customers (up to 6 digits)

| The annual amount of heat delivered to all customers (dwellings and non-domestic),

thereby indicating the scale of the network.

| mwhPa | | 22 | | Individual dwelling heat

metering (1 digit)

| Whether the supply of heat to each individual dwelling is metered.1 for yes, 0 for no | isPropMetered | | 23 | | Total MWh of heat per

annum delivered to dwellings (up to 6 digits)

| The annual amount of heat delivered to dwellings. | mwhPpropPa | | 24 | | Distribution route length in

metres (up to 6 digits)

| The total length of the network heat distribution pipework route. In the case of

underground pipework it is the total trench length containing pipework plus any internal distribution route within apartment block risers and laterals. It includes both flow and return water pipes i.e. it is not the sum of the flow and return pipework.

| lenPipeTotal | | 25 | | Linear loss

(up to 7 digits eg xxx.xxx)

| The average heat loss per metre length of network heat distribution pipework route in

W/m.

| lossLinear | | 26 | X | Distribution loss factor

(up to 4 chs, e.g. x.xx)

| Factor that allows for losses from the heat distribution network, see SAP section C3.

Applicable to all connected premises.

| lossFactorLinear | | 27 | | Pumping electrical energy

(up to 6 digits, e.g. xxxxxx)

| Annual electrical energy for pumping in the heat distribution network in kWh/year. | kwhPumpPa | | 28 | X | Pumping electrical energy

per dwelling (up to 6 digits, e.g. xxxx.xx)

| Annual electrical energy for pumping in the heat distribution network attributed to

each dwelling, in kWh/year.

| kwhPumpPpropPa | | 29 | | Carbon dioxide intensity of

heat (up to 6 digits e.g. xx.xxx

| The average carbon dioxide intensity of the heat delivered to customers. in kg/kWh.

This value takes into account all factors which influence the emissions associated with the heat supplied. It is based on the heat delivered to individual dwellings, and to the building in the case of non-domestic premises.

| intensityCarbon | | 30 | | Primary energy factor of

heat up to 5 digits e.g. xx.xx)

| The average primary energy factor of the heat delivered to customers. This value

takes into account all factors which influence the primary energy associated with the heat supplied. It is based on the heat delivered to individual dwellings, and to the building in the case of non-domestic premises.

| energyFactorPrimary | | 31 | X | Number of heat sources

(1 digit)

| Number of separate heat sources (between 1 and 5). Heat sources are considered

separate if they differ in heat source type or fuel, e.g. a set of boilers each using the same fuel are treated as one source with efficiency as defined in C2 of the SAP specification.

| nHeatSource | | 32 | X | A: Heat source type

(1 digit)

| Group A: Type of heat generator, encoded as 1: CHP; 2: boilers; 3: heat pump; 4:

waste heat from power station; 5: geothermal. If CHP is part of the installation it is given as Group A.

| typeHeatSource | | 33 | X | A: Community fuel

(2 digits)

| Group A: The community fuel to which the data relates, either one of community fuel

codes in SAP Table 12, or 99 in the case of a fuel not in SAP Table 12.

| typeFuel | | 34 | X | A: Fuel description

(up to 30 chs)

| Group A: Description of the fuel in the preceding field. May be blank if field 33 is not

| desFuel | | 35 | X | A: Heat efficiency

(up to 4 digits, e.g. xx.x)

| Group A: Heat efficiency of heat source in % gross. | | 36 | X | A: Power efficiency

(up to 4 digits, e.g. xx.x)

| Group A: Power efficiency of CHP plant in % gross. Blank if not applicable. | | 37 | X | A: Heat fraction

(up to 5 digits, e.g. x.xxx)

| Group A: The fraction of heat supplied by the community heat network attributable to

the heat source.

| | 38 | X | A: Community fuel CO2

emission factor (up to 5 chs, e.g. xxx.x)

| Group A: The CO2 emission factor in kg/kWh for the fuel. Blank when field 33 is not

| | 39 | X | A: Community fuel primary

energy factor (up to 4 chs, e.g. x.xx

| Group A: The primary energy factor for the fuel (dimensionless). Blank when field 33

is not 99.

| | 40 to 31+8n | X | Group B, C, D, E | Group B, C, D, E. Set of data in the same format as those for group A for other heat

sources. n is the value in field 31.

|

Substations

The next low hanging fruit for a network protocol is a sub-station. While plantrooms and HIUs will differ, substations are pretty generic - the process of using a plate heat exchanger to transfer heat from one circuit to another, using one or more plates.

The principles demonstrated on a substation can be applied to other equipment groups, such as boilers. pumps or thermal stores.

The sub-station detailed here makes use of two plates to provide redundancy or duty/assist operation.

The full topic would start with:

network_id/publisher_id/

Where network_id is the network index number (= field 1), and publisher_id is the user name for access to the database (the substation control panel).

For example, the topic for a substations output temperature may look like:

myNetwork/subStB2/subSt/dat/tCo

Not all topics will be present as some sensors may not be included, for example flow rate readings require the inclusion of heat meter data typically.

Substation Entities

Substation Fields

Heat Meters and M-Bus Devices

Heat Meters

In the topic structure, the publisher level represents the unique identifier (serial number) of the M-Bus Gateway the meter is connected to, while the device_id would be the heat meter serial number.

Boilers

Plantrooms

In addition to boilers, a plantroom in a building will have other sub-systems.

Most topics can be taken from the equivalent for a sub-station or a boiler.

Block of Load

E.g. a building.

The main purpose of blocks is to collate performance data and alarms from devices in a group, to produce a summary that can be passed up the line with minimal data footprint.

Individual device values are not so important as total and average values. Key block metrics would normally be provided over past 24 hours.

At a hardware level, MQTT devices responsible for producing block data (from a stream of HIU data for example) would require persistent data storage (locally or remotely) in order to calculate long term statistics. As data is summarised at the block level, there is no persistent storage of end-device data (such as HIU data).

Hydraulic Interface Units (HIUs)

Note that some legacy names are still to be adjusted to camel case.

See Node-HIU Switch.

The following table shows the structure of standard topics available for each HIU.

Readings

Settings

Statistics

System Variables

Node Settings

JSON

JSON is the web standard for describing data. It is best explained with a demonstration.

Given we have two PCDB data fields to store (as an example) we may have:

myNetwork/aab3458cd2ef345c/net/stat/idN = 12345678
myNetwork/aab3458cd2ef345c/net/stat/des = "This is an example heat network"

In JSON this would look like (formatted):

{
"MyNetwork": {
"aab3458cd2ef345c": {
"net": {
"stat": {
"idN": 12345678,
"des": "This is an example heat network"
}
}
}
}
}

Or unformatted:

{"MyNetwork":{"aab3458cd2ef345c":{"net":{"stat":{"idN": 12345678,"desNet":"This is an example heat network"}}}}}

Timestamped Data

To store data with Unix timestamps, the format would be as follows (for the output from a boiler over time for example):

{
"MyNetwork": {
"aab3458cd2ef345c": {
"b1": {
"dat": {
"tOut": {
"1551374962": 75.4,
"1551374972": 74.5,
"1551374982": 73.7,
"1551374992": 72.3,
"1551375002": 71.8
}
}
}
}
}
}

Non-Protocol Related Standards

MQTT Ports

The default port for MQTT is 1883.

IP Addresses